diff --git a/docs/architecture/contract-abi.md b/docs/architecture/contract-abi.md index 09c7b47c..9399149e 100644 --- a/docs/architecture/contract-abi.md +++ b/docs/architecture/contract-abi.md @@ -1,145 +1,68 @@ --- -icon: fontawesome/solid/file +icon: fontawesome/solid/file-code --- # Contract ABI -To interact with smart contracts, Koinos tooling requires an Application Binary Interface (ABI). This ABI is a json file that describes what functions a contract has available and how to interact with it. Here is an example ABI for the KOIN Contract. - -``` json -{ - "methods" : { - "name": { - "argument" : "koinos.contracts.token.name_arguments", - "return" : "koinos.contracts.token.name_result", - "entry_point" : "0x76ea4297", - "description" : "Returns the token's name", - "read_only" : true - }, - "symbol": { - "argument" : "koinos.contracts.token.symbol_arguments", - "return" : "koinos.contracts.token.symbol_result", - "entry_point" : "0x7e794b24", - "description" : "Returns the token's symbol", - "read_only" : true - }, - "decimals": { - "argument" : "koinos.contracts.token.decimals_arguments", - "return" : "koinos.contracts.token.decimals_result", - "entry_point" : "0x59dc15ce", - "description" : "Return the token's decimal precision", - "read_only" : true - }, - "total_supply": { - "argument" : "koinos.contracts.token.total_supply_arguments", - "return" : "koinos.contracts.token.total_supply_result", - "entry_point" : "0xcf2e8212", - "description" : "Mints the token's total supply", - "read_only" : true - }, - "balance_of": { - "argument" : "koinos.contracts.token.balance_of_arguments", - "return" : "koinos.contracts.token.balance_of_result", - "entry_point" : "0x15619248", - "description" : "Checks the balance at an address", - "read_only" : true - }, - "transfer": { - "argument" : "koinos.contracts.token.transfer_arguments", - "return" : "koinos.contracts.token.transfer_result", - "entry_point" : "0x62efa292", - "description" : "Transfers the token", - "read_only" : false - }, - "mint": { - "argument" : "koinos.contracts.token.mint_arguments", - "return" : "koinos.contracts.token.mint_result", - "entry_point" : "0xc2f82bdc", - "description" : "Mints the token", - "read_only" : false - } - }, - "types" : "CssCChRrb2lub3Mvb3B0aW9ucy5wcm90bxIGa29pbm9zGiBnb29nbGUvcHJvdG9idWYvZGVzY3JpcHRvci5wcm90byptCgpieXRlc190eXBlEgoKBkJBU0U2NBAAEgoKBkJBU0U1OBABEgcKA0hFWBACEgwKCEJMT0NLX0lEEAMSEgoOVFJBTlNBQ1RJT05fSUQQBBIPCgtDT05UUkFDVF9JRBAFEgsKB0FERFJFU1MQBjpiChFrb2lub3NfYnl0ZXNfdHlwZRIdLmdvb2dsZS5wcm90b2J1Zi5GaWVsZE9wdGlvbnMY0IYDIAEoDjISLmtvaW5vcy5ieXRlc190eXBlUg9rb2lub3NCeXRlc1R5cGWIAQFCLlosZ2l0aHViLmNvbS9rb2lub3Mva29pbm9zLXByb3RvLWdvbGFuZy9rb2lub3NiBnByb3RvMwqQBwoia29pbm9zL2NvbnRyYWN0cy90b2tlbi90b2tlbi5wcm90bxIWa29pbm9zLmNvbnRyYWN0cy50b2tlbhoUa29pbm9zL29wdGlvbnMucHJvdG8iEAoObmFtZV9hcmd1bWVudHMiIwoLbmFtZV9yZXN1bHQSFAoFdmFsdWUYASABKAlSBXZhbHVlIhIKEHN5bWJvbF9hcmd1bWVudHMiJQoNc3ltYm9sX3Jlc3VsdBIUCgV2YWx1ZRgBIAEoCVIFdmFsdWUiFAoSZGVjaW1hbHNfYXJndW1lbnRzIicKD2RlY2ltYWxzX3Jlc3VsdBIUCgV2YWx1ZRgBIAEoDVIFdmFsdWUiGAoWdG90YWxfc3VwcGx5X2FyZ3VtZW50cyIvChN0b3RhbF9zdXBwbHlfcmVzdWx0EhgKBXZhbHVlGAEgASgEQgIwAVIFdmFsdWUiMgoUYmFsYW5jZV9vZl9hcmd1bWVudHMSGgoFb3duZXIYASABKAxCBIC1GAZSBW93bmVyIi0KEWJhbGFuY2Vfb2ZfcmVzdWx0EhgKBXZhbHVlGAEgASgEQgIwAVIFdmFsdWUiXgoSdHJhbnNmZXJfYXJndW1lbnRzEhgKBGZyb20YASABKAxCBIC1GAZSBGZyb20SFAoCdG8YAiABKAxCBIC1GAZSAnRvEhgKBXZhbHVlGAMgASgEQgIwAVIFdmFsdWUiJwoPdHJhbnNmZXJfcmVzdWx0EhQKBXZhbHVlGAEgASgIUgV2YWx1ZSJACg5taW50X2FyZ3VtZW50cxIUCgJ0bxgBIAEoDEIEgLUYBlICdG8SGAoFdmFsdWUYAiABKARCAjABUgV2YWx1ZSIjCgttaW50X3Jlc3VsdBIUCgV2YWx1ZRgBIAEoCFIFdmFsdWUiKgoOYmFsYW5jZV9vYmplY3QSGAoFdmFsdWUYASABKARCAjABUgV2YWx1ZSJ5ChNtYW5hX2JhbGFuY2Vfb2JqZWN0EhwKB2JhbGFuY2UYASABKARCAjABUgdiYWxhbmNlEhYKBG1hbmEYAiABKARCAjABUgRtYW5hEiwKEGxhc3RfbWFuYV91cGRhdGUYAyABKARCAjABUg5sYXN0TWFuYVVwZGF0ZUI+WjxnaXRodWIuY29tL2tvaW5vcy9rb2lub3MtcHJvdG8tZ29sYW5nL2tvaW5vcy9jb250cmFjdHMvdG9rZW5iBnByb3RvMw==" -} -``` - -The fields for each entry in `methods` are pretty self explanatory. The argument and return type names are fully qualified types generated from Protobuf. In this case the generating file is: - -``` proto -syntax = "proto3"; - -package koinos.contracts.token; -option go_package = "github.com/koinos/koinos-proto-golang/koinos/contracts/token"; - -import "koinos/options.proto"; - -message name_arguments {} -message name_result { - string value = 1; -} +A Koinos contract Application Binary Interface (ABI) is a JSON description of +the contract's callable interface. It tells tools how to map a method name to an +entry point and how to encode the method's protobuf arguments and result. -message symbol_arguments {} +An ABI is not the contract bytecode, and it does not prove that the deployed +contract implements the described behavior. -message symbol_result { - string value = 1; -} +## Method descriptions -message decimals_arguments {} +An ABI method record identifies: -message decimals_result { - uint32 value = 1; -} +| Field | Purpose | +| --- | --- | +| Method name | Human-readable name used by SDKs and API tools | +| Argument type | Fully qualified protobuf message for the input | +| Result type | Fully qualified protobuf message for the output | +| Entry point | 32-bit value dispatched by the contract | +| Read-only flag | Indicates whether tooling should use a read-only call or build a transaction | +| Description | Optional human-readable explanation | -message total_supply_arguments {} +The entry point, argument type, and result type must match the deployed +contract. A read-only flag helps tooling choose the request path, but Chain +still enforces whether execution attempts to change state. -message total_supply_result { - uint64 value = 1 [jstype = JS_STRING]; -} +## Type descriptors -message balance_of_arguments { - bytes owner = 1 [(btype) = ADDRESS]; -} +The ABI's `types` value contains a Base64-encoded protobuf descriptor set. It +allows a tool to discover the message fields needed to encode arguments and +decode results without compiling the original `.proto` files into that tool. -message balance_of_result { - uint64 value = 1 [jstype = JS_STRING]; -} +This descriptor is a schema, not a sample payload. The actual argument and +result values are serialized separately for each call. -message transfer_arguments { - bytes from = 1 [(btype) = ADDRESS]; - bytes to = 2 [(btype) = ADDRESS]; - uint64 value = 3 [jstype = JS_STRING]; -} +## How the ABI is used -message transfer_result { - bool value = 1; -} - -message mint_arguments { - bytes to = 1 [(btype) = ADDRESS]; - uint64 value = 2 [jstype = JS_STRING]; -} +```mermaid +flowchart TB + ABI["ABI: name, entry point, types"] --> Tool["SDK or API tool"] + Values["Application values"] --> Tool + Tool --> Encoded["Protobuf argument bytes"] + Encoded --> Chain["Chain contract call"] + Chain --> Result["Protobuf result bytes"] + Result --> Tool +``` -message mint_result { - bool value = 1; -} +SDKs use the ABI to offer named contract methods instead of requiring users to +calculate entry points and serialize raw bytes manually. Contract Meta Store +indexes metadata published on-chain so API clients can look up an ABI by +contract ID. -message balance_object { - uint64 value = 1 [jstype = JS_STRING]; -} +Because a derived metadata index can lag Chain, applications that require a +specific interface should verify that the ABI matches the contract version they +intend to call. -message mana_balance_object { - uint64 balance = 1 [jstype = JS_STRING]; - uint64 mana = 2 [jstype = JS_STRING]; - uint64 last_mana_update = 3 [jstype = JS_STRING]; -} -``` +For generating and using an ABI during development, continue with +[Smart Contract Development](../contracts/index.md). -The Base64 encoded string for the field `types` is a Base64 encoded protobuf descriptor for these types. To generate this descriptor you can run the following commands in `koinos-proto`. - -```console -$ protoc --descriptor_set_out=koin.pb koinos/contracts/token/token.proto koinos/options.proto -$ cat koin.pb | base64 -``` +## Versioned sources -!!! note - You need to include both the contract proto file (`koinos/contracts/token/token.proto` and any non-protobuf files it includes (`koinos/options.proto`). This will create the smallest possible ABI that can be used with various Koinos tooling. \ No newline at end of file +- [KOIN contract ABI at the inspected system-contract revision](https://github.com/koinos/koinos-contracts-as/blob/aef57bdb8a5960ec2b799ee0f17bf7a25bb5de85/contracts/koin/abi/koin.abi) +- [`koinos-contract-meta-store` v1.1.0](https://github.com/koinos/koinos-contract-meta-store/tree/64e803e1db1a9bb2946ae379ddad0e5611442ec5) +- [Contract metadata schema in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/contract_meta_store/contract_meta_store.proto) diff --git a/docs/architecture/index.md b/docs/architecture/index.md index 498c2473..9a149de0 100644 --- a/docs/architecture/index.md +++ b/docs/architecture/index.md @@ -1,84 +1,93 @@ --- hide: -- toc + - toc --- # Architecture -The architecture section of the Koinos documentation provides a comprehensive overview of the underlying design and components that power the Koinos blockchain. Explore the innovative features, consensus mechanisms, and scalability solutions that differentiate Koinos from other blockchain platforms. Learn about the Koinos Virtual Machine (KVM), resource management strategies, and the unique approach to smart contract execution. + +Koinos separates consensus, storage, networking, indexing, and public APIs into +cooperating services. Smart contracts provide application logic and can also +replace selected protocol behavior through the system-call architecture. + +This chapter explains those boundaries and the consistency rules between them. +For commands and production procedures, use [Node Operators](../nodes/index.md). +For contract development, use +[Smart Contract Development](../contracts/index.md).
-- :fontawesome-solid-circle-nodes:{ .lg .middle } __Microservices__ +- :fontawesome-solid-circle-nodes:{ .lg .middle } **Microservices** --- - - In the architecture of the Koinos blockchain, microservices play a crucial role in promoting scalability, flexibility, and maintainability. By breaking down complex functionalities into smaller, independent services, Koinos adopts a modular approach that allows for easier development, deployment, and scaling of specific blockchain components, enhancing overall system resilience and performance. -

+ Understand the services inside a Koinos node, which service owns each kind + of state, and how optional API and index services extend the core node. - [:octicons-arrow-right-24: The nuts and bolts](microservices.md) + [:octicons-arrow-right-24: Explore the node](microservices.md) -- :fontawesome-solid-network-wired:{ .lg .middle } __Interprocess communication__ +- :fontawesome-solid-network-wired:{ .lg .middle } **Internal messaging** --- - Interprocess communication (IPC) is fundamental to the architecture of the Koinos blockchain, enabling different components and microservices to communicate and collaborate efficiently. Koinos utilizes IPC mechanisms such as message queues and remote procedure calls (RPC) to facilitate secure and reliable communication between nodes, ensuring seamless coordination and data exchange within the blockchain network. -

+ See how protobuf RPC requests and broadcasts move through RabbitMQ, and why + this internal bus is different from the peer-to-peer network. - [:octicons-arrow-right-24: Internal communication](interprocess-communication.md) + [:octicons-arrow-right-24: Follow a message](interprocess-communication.md) -- :fontawesome-solid-fire:{ .lg .middle } __Proof-of-Burn__ +- :fontawesome-solid-code:{ .lg .middle } **Smart contract execution** --- - - Proof-of-Burn (PoB) is a consensus mechanism used by Koinos where participants burn tokens, demonstrating commitment to the network. The act of burning tokens reduces the circulating supply and increases the probability of being selected as a block validator based on the size of the burn relative to the total amount burned in a given period, ensuring a fair and efficient method of block producer selection. + Learn how Chain executes WebAssembly contracts, separates read-only calls + from transactions, records state, and emits events. - [:octicons-arrow-right-24: A novel consensus algorithm](proof-of-burn.md) + [:octicons-arrow-right-24: Enter the runtime](smart-contracts.md) -- :fontawesome-solid-cubes:{ .lg .middle } __Serialization__ +- :fontawesome-solid-file-code:{ .lg .middle } **ABI and serialization** --- - Serialization is a critical aspect of the Koinos blockchain architecture, responsible for encoding and decoding structured data for efficient storage and transmission. Koinos uses serialization frameworks like Protocol Buffers to define data schemas, optimize data transmission, and ensure interoperability across different components of the blockchain network. -

+ Understand how an ABI describes contract entry points and how Protocol + Buffers encode data across APIs, services, transactions, and contracts. - [:octicons-arrow-right-24: Encoding and decoding](serialization.md) + [:octicons-arrow-right-24: Understand the data](contract-abi.md) -- :fontawesome-solid-code:{ .lg .middle } __Smart contracts__ +- :fontawesome-solid-left-right:{ .lg .middle } **System calls** --- - Smart contracts are a foundational component of the Koinos blockchain architecture, enabling decentralized and self-executing agreements. Koinos supports smart contracts which are executed on the Koinos Virtual Machine (KVM) to enforce trustless and deterministic execution of code on the blockchain. -


+ Learn how contracts access blockchain capabilities and how system contracts + can replace selected native behavior without changing the node executable. - [:octicons-arrow-right-24: A turing complete solution](smart-contracts.md) + [:octicons-arrow-right-24: Cross the runtime boundary](system-calls.md) -- :fontawesome-solid-file:{ .lg .middle } __Contract ABI__ +- :fontawesome-solid-microchip:{ .lg .middle } **Resource model** --- - - Contract ABIs (Application Binary Interfaces) define the interface and interaction points of smart contracts on the Koinos blockchain. These interfaces specify the methods, parameters, and return types that can be accessed and invoked by external entities interacting with smart contracts, facilitating interoperability and enabling seamless communication between different components of the blockchain ecosystem. + See how Koinos measures compute, network bandwidth, and disk storage and + charges those resources in Resource Credits instead of conventional gas + fees. - [:octicons-arrow-right-24: Defining your interface](contract-abi.md) + [:octicons-arrow-right-24: Follow resource accounting](resources.md) -- :fontawesome-solid-microchip:{ .lg .middle } __Resources__ +- :fontawesome-solid-fire:{ .lg .middle } **Proof of Burn** --- - Blockchain resources in the context of Koinos refer to the computational and storage resources required for blockchain operations such as transaction processing and smart contract execution. Koinos implements resource management mechanisms like Resource Credits (RC) and payer semantics to efficiently allocate and regulate these resources, ensuring fair usage and optimal performance of the blockchain network. -


- - [:octicons-arrow-right-24: Compute, network, and disk oh my!](resources.md) + Understand the relationship between KOIN, Virtual Hash Power, block + production eligibility, and the VHP consumed during production. -- :fontawesome-solid-left-right:{ .lg .middle } __System calls__ - - --- + [:octicons-arrow-right-24: Understand consensus](proof-of-burn.md) - System calls are fundamental components of the Koinos blockchain architecture, enabling smart contracts to interact with the underlying blockchain system and external services. These calls provide secure and controlled access to blockchain functionalities such as accessing data, performing transactions, or invoking other smart contracts, allowing developers to build complex decentralized applications (dApps) with flexible and robust capabilities on the Koinos platform. -

+
- [:octicons-arrow-right-24: From KVM to native](system-calls.md) +## Source baseline - \ No newline at end of file +The service architecture in this chapter follows the version set declared by +the official Koinos deployment bundle at commit +[`821674672e699bf56e94d7c0e8bce122e83d1482`](https://github.com/koinos/koinos/tree/821674672e699bf56e94d7c0e8bce122e83d1482). +RPC and broadcast definitions use +[`koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/tree/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80). +Versioned links on each page identify the implementation inspected for that +explanation. diff --git a/docs/architecture/interprocess-communication.md b/docs/architecture/interprocess-communication.md index 1447d543..d7855178 100644 --- a/docs/architecture/interprocess-communication.md +++ b/docs/architecture/interprocess-communication.md @@ -2,49 +2,78 @@ icon: fontawesome/solid/network-wired --- -# Interprocess communication -Communication between microservices is accomplished utilizing the AMQP 0.9.1 protocol. The Koinos cluster uses the hub and spoke model. Messages between microservices can either be RPC or broadcast (see **Table 1** below for a more detailed explanation). Messages originating from a particular microservice will be directed through an exchange on RabbitMQ; through `koinos.rpc` and `koinos.event` for RPC and broadcasts, respectively. +# Internal messaging -_**Table 1.** A table containing information about the types of messages and exchanges within a Koinos cluster._ +Koinos microservices exchange Protocol Buffer messages through RabbitMQ using +AMQP 0.9.1. This internal bus supports two different communication patterns: +RPC and broadcasts. -|Message type|Exchange|Example request(s)|Characteristics| -|---|---|---|---| -|RPC |`koinos.rpc` |`get_head_info`
`get_blocks_by_height`
`get_account_nonce`
`get_chain_id` |The traditional request/response
model| -|Broadcast |`koinos.event`|`block_accepted`
`transaction_accepted`
`block_irreversible`
`fork_heads` |An event driven model - messages
are generally sent from one to many| +RabbitMQ connects services inside one Koinos node. P2P is the separate protocol +boundary used to communicate with other nodes. ---- ## RPC -Each microservice that serves RPC requests binds to a durable queue. The system is designed such that each microservice can be scaled up and down based on the load required by the particular Koinos cluster. This is implemented via a competitive consumer model, i.e., multiple instances of a microservice competing to service requests off a single queue. -From a high level, each service makes requests by sending an RPC message to the `koinos.rpc` exchange on the RabbitMQ server. RabbitMQ directs messages from the `koinos.rpc` exchange to the corresponding queue using a routing key. The routing key matches the name of the destination queue. The response messages are matched to the request using a Correlation ID - that is attached to the original request message and the resulting response. +An RPC has a request, one destination service, and a response. A service sends a +protobuf request to the `koinos.rpc` exchange, and RabbitMQ routes it to the +queue for the target service. A correlation identifier associates the response +with the original request. ```mermaid +sequenceDiagram + participant P2P + participant MQ as RabbitMQ + participant Chain - sequenceDiagram - Koinos P2P->>+RabbitMQ: get_head_info_request - RabbitMQ->>+Koinos Chain: get_head_info_request - Koinos Chain-->>-RabbitMQ: get_head_info_response - RabbitMQ-->>-Koinos P2P: get_head_info_response + P2P->>MQ: get_head_info request + MQ->>Chain: route to Chain + Chain-->>MQ: get_head_info response + MQ-->>P2P: correlated response ``` -_**Figure 1.** A diagram demonstrating the data path of an RPC request from Koinos P2P to Koinos Chain._ +API gateways use this same path after translating an external JSON-RPC or gRPC +request. A gateway timeout does not by itself reveal whether the destination +finished processing a state-changing request. ---- -## Broadcast -When an event occurs within a Koinos cluster, such as when a block is accepted into a fork of the chain, a broadcast message is emitted (as shown in **Figure 2** below). The broadcast message is not directed to any particular consumer, it is intended for any consumer who may be interested. This essentially behaves similar to a publisher/subscriber paradigm where a message is sent on a particular topic. +## Broadcasts -```mermaid +A broadcast announces an event to every interested subscriber. Broadcasts use +the `koinos.event` exchange and topic-based routing keys. - flowchart - B[Koinos Chain] -- block_accepted --> A((RabbitMQ)) - A -- block_accepted --> C[Koinos Block Store] - A -- block_accepted --> D[Koinos Transaction Store] - A -- block_accepted --> E[Koinos P2P] - A -- block_accepted --> F[Koinos Mempool] +For example, after Chain accepts a block, Block Store can persist it, Mempool +can update pending transactions, P2P can propagate it, and index services can +update their derived views. + +```mermaid +flowchart TB + Chain["Chain"] -- "block accepted" --> MQ(("RabbitMQ")) + MQ --> BlockStore["Block Store"] + MQ --> Mempool["Mempool"] + MQ --> P2P["P2P"] + MQ --> Indexes["Derived indexes"] ``` -_**Figure 2.** A diagram demonstrating the data path of a `block_accepted` message._ +The versioned broadcast schema includes accepted and irreversible blocks, +accepted and failed transactions, Mempool acceptance, fork heads, gossip +status, and contract event parcels. + +## Delivery and consistency + +Messaging separates services, but it does not make their databases atomic: + +- Chain can advance before a downstream index processes the broadcast. +- A consumer must handle redelivery without corrupting its state. +- Recent accepted-block data can change after a fork. +- RPC availability depends on RabbitMQ and the destination service. +- Replicating a stateful writer or broadcast consumer requires explicit + ownership and consistency support; it must not be inferred from the + microservice design. + +RabbitMQ queue durability, credentials, exposure, and recovery are deployment +concerns documented under [Node Operators](../nodes/index.md). -The advantage of a broadcast message is that it allows for the loose coupling of services. It also facilitates the seamless integration of user-created microservices. Reacting to the acceptance of a block, for example, will likely be leveraged by most custom applications and does not require RPC or polling. +## Versioned sources -To receive broadcasts, one must create an anonymous queue and bind it to the `koinos.event` exchange. Using the routing key, one may specify topics of interest. In the case of block acceptance, the corresponding routing key would be `koinos.block.accept`. Wildcards may be used to simplify this process. For example, if an application must be notified about all events involving a block, the routing key can be specified as `koinos.block.*`. \ No newline at end of file +- [RabbitMQ in the official Compose topology](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) +- [RPC envelope in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/rpc.proto) +- [Broadcast definitions in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/broadcast/broadcast.proto) +- [AMQP 0.9.1 specification](https://www.rabbitmq.com/amqp-0-9-1-reference) diff --git a/docs/architecture/microservices.md b/docs/architecture/microservices.md index dcc3eb4c..bc10de9e 100644 --- a/docs/architecture/microservices.md +++ b/docs/architecture/microservices.md @@ -3,47 +3,89 @@ icon: fontawesome/solid/circle-nodes --- # Microservices -A microservice architecture has many advantages over a more traditional monolithic architecture. By breaking up a complex application into a set of loosely coupled services, software becomes highly maintainable and easily verifiable while providing a great degree of deployment flexibility. Improving or replacing microservices become a trivial task - this allows for low-risk upgrade paths. An additional benefit that should not be underestimated is the ability to choose the programming language best fit for the microservice at hand. -With a microservice architecture, onboarding engineers becomes a more feasible task as engineers can more easily master one or more services without having to understand the details of the larger complicated system. This will lead to more productive hires and higher quality contributions. +A Koinos node is composed of services with separate responsibilities. RabbitMQ +provides the internal message bus. Chain validates consensus state, P2P connects +the node to peers, and the remaining services store artifacts, maintain working +state, build query indexes, produce blocks, or expose APIs. ---- -## Cluster anatomy -The Koinos cluster implements the Koinos protocol leveraging the benefits of microservice architectures. The microservices provided by Koinos Group facilitates all the necessary functions to power the Koinos blockchain (see **Table 1** below for a complete list). - -_**Table 1.** A table containing information about the core microservices of a Koinos cluster._ - -|Microservice|Language|Responsibilities| -|---|---|---| -|[Koinos Chain](https://github.com/koinos/koinos-chain) |C++|Processing blocks and maintaining the state of the chain| -|[Koinos Block Store](https://github.com/koinos/koinos-block-store) |Golang|Storing block information| -|[Koinos P2P](https://github.com/koinos/koinos-p2p) |Golang|P2P communication between node clusters| -|[Koinos Mempool](https://github.com/koinos/koinos-mempool) |C++|Storing transactions that have yet to be included in blocks| -|[Koinos Transaction Store](https://github.com/koinos/koinos-transaction-store) |Golang|Storing transaction information| -|[Koinos Block Producer](https://github.com/koinos/koinos-block-producer) |C++|The production of blocks| -|[Koinos JSON-RPC](https://github.com/koinos/koinos-jsonrpc) |Golang|Providing API access from outside the cluster| -|[Koinos gRPC](https://github.com/koinos/koinos-grpc) |C++|Providing API access from outside the cluster| -|[Koinos Contract Meta Store](https://github.com/koinos/koinos-contract-meta-store) |Golang|Providing ABI data for smart contracts| -|[Koinos Account History](https://github.com/koinos/koinos-account-history) |C++|Providing records for each address| - ---- -## Internal communication -Communication between microservices is accomplished by taking advantage of the battle hardened _Advanced Message Queue Protocol_ ([AMQP 0.9.1](https://www.amqp.org/specification/0-9-1/amqp-org-download)) as implemented by [RabbitMQ](https://www.rabbitmq.com/). Each microservice maintains a connection to RabbitMQ which it uses to send and receive _Remote Procedure Calls_ (RPC) as well as broadcast messages. Microservices avoid the need for polling by utilizing broadcast messages in order to implement an event driven paradigm. +Separating these responsibilities makes the node modular, but it also means +that process health and data consistency are different questions. An API can be +reachable while its target service is unavailable or catching up. ```mermaid - - flowchart - B[Koinos Chain] <--> A(("RabbitMQ\n(AMQP 0.9.1)")) - C[Koinos Block Store] <--> A - D[Koinos Mempool] <--> A - E[Koinos P2P] <--> A - A <--> F[Koinos Block Producer] - A <--> G[Koinos JSONRPC] - A <--> H[Koinos Transaction Store] - A <--> I[Koinos Contract Meta Store] +flowchart TB + External["Peers, applications, and tools"] + Interfaces["P2P and API gateways"] + Bus["RabbitMQ internal messaging"] + Services["Chain, Mempool, Block Store, indexes, and Block Producer"] + External <--> Interfaces + Interfaces <--> Bus + Bus <--> Services ``` -_**Figure 1.** A diagram demonstrating the interprocess communication data flow within a Koinos cluster._ -[More about interprocess communication »](interprocess-communication.md) +The arrows show communication relationships. They do not imply that every +service can write every database or that all services can be replicated without +coordination. + +## Services in the official deployment bundle + +The selected +[Compose topology](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) +contains a core node and optional production, API, and index services. + +| Service | Role | +| --- | --- | +| [RabbitMQ](interprocess-communication.md) | Routes internal RPC requests and broadcasts | +| [Chain](microservices/koinos-chain.md) | Validates blocks and transactions, executes contracts, and owns canonical state | +| [Mempool](microservices/mempool.md) | Maintains the fork-aware pending-transaction view | +| [Block Store](microservices/block-store.md) | Stores blocks and receipts for retrieval | +| [P2P](microservices/p2p.md) | Connects to peers, gossips data, and coordinates synchronization | +| [Block Producer](microservices/block-producer.md) | Optionally assembles, signs, and submits blocks | +| [JSON-RPC](microservices/json-rpc.md) | Exposes an HTTP JSON-RPC gateway | +| [gRPC](microservices/grpc.md) | Exposes a typed protobuf gateway | +| [REST](microservices/rest.md) | Exposes REST/OpenAPI endpoints through JSON-RPC | +| [Transaction Store](microservices/transaction-store.md) | Builds a transaction lookup index | +| [Contract Meta Store](microservices/contract-meta-store.md) | Builds a contract metadata and ABI index | +| [Account History](microservices/account-history.md) | Builds a fork-aware account activity index | + +The core Compose services are RabbitMQ, Chain, Mempool, Block Store, and P2P. +The other services are enabled through Compose profiles in this release. That +deployment grouping can change, so operator configuration should always follow +the selected release rather than this architecture summary. + +## State ownership + +| State | Service | Consistency meaning | +| --- | --- | --- | +| Consensus state | Chain | Authoritative for local validation and execution | +| Blocks and receipts | Block Store | Durable artifacts; Chain still decides validity | +| Pending transactions | Mempool | Transient, fork-aware working state | +| Transaction lookup | Transaction Store | Derived index that can lag Chain | +| Contract metadata | Contract Meta Store | Derived index that can lag or follow a fork | +| Account activity | Account History | Derived, fork-aware index | +| API request state | JSON-RPC, gRPC, REST | Gateway state only; not blockchain state | + +An accepted block can still be replaced before it becomes irreversible. +Services that index accepted blocks must therefore follow fork changes and +irreversible-block information. A derived index can be incomplete while Chain +is already synchronized. + +## Internal and external boundaries + +- [Internal messaging](interprocess-communication.md) carries service RPC and + broadcasts through RabbitMQ. +- [P2P](microservices/p2p.md) exchanges blocks and transactions with other + Koinos nodes. +- API gateways translate external protocols into internal service requests. +- Smart contracts execute inside the Chain service's WebAssembly runtime. + +For selecting services and operating their data, continue with +[Node Operators](../nodes/microservices.md). + +## Versioned sources -Because of the extensibility of the Koinos cluster, users can develop custom microservices that provide additional functionality. User-created microservices have first class citizenship - in other words, they have the same capabilities of any core microservice provided by Koinos Group. This enables engineers and entrepreneurs to provide unique business propositions that would otherwise be difficult to implement - no longer is polling and parallel data storage required when you have access to the core event driven system. \ No newline at end of file +- [Official service versions](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/env.example) +- [Official Compose topology](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) +- [RPC service definitions in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/services.proto) +- [Broadcast definitions in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/broadcast/broadcast.proto) diff --git a/docs/architecture/microservices/account-history.md b/docs/architecture/microservices/account-history.md index e69de29b..0bbdb8b4 100644 --- a/docs/architecture/microservices/account-history.md +++ b/docs/architecture/microservices/account-history.md @@ -0,0 +1,37 @@ +--- +icon: fontawesome/solid/clock-rotate-left +--- + +# Account History + +Account History builds a per-account activity index from accepted blocks, +transactions, receipts, and events. It provides historical queries that do not +belong in Chain's consensus state. + +## Dependencies and inputs + +The service connects to RabbitMQ and consumes accepted-block and +irreversible-block broadcasts. In the official Compose topology it also depends +on Chain and Block Store, which it uses to determine progress and retrieve +stored blocks while catching up. + +Its RPC interface provides paginated account-history lookup. + +## State and consistency + +The selected release uses a fork-aware Koinos state database backed by RocksDB. +The index can contain recent accepted history that is not yet irreversible and +must follow the selected fork when Chain changes heads. + +Account History is a derived view. It can be behind Chain, and it is not +authoritative for a current balance, nonce, or contract state. Pagination over +a moving head can also observe new history between requests. + +If the service is unavailable, account-history queries fail while Chain and +block validation can continue. + +## Versioned sources + +- [`koinos-account-history` v1.1.0](https://github.com/koinos/koinos-account-history/tree/1d592c40ddd06c022eab3153266bd428752c6ded) +- [Account History RPC schema in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/account_history/account_history_rpc.proto) +- [Current official Compose relationship](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/docs/architecture/microservices/block-producer.md b/docs/architecture/microservices/block-producer.md index e69de29b..8081fd6d 100644 --- a/docs/architecture/microservices/block-producer.md +++ b/docs/architecture/microservices/block-producer.md @@ -0,0 +1,48 @@ +--- +icon: fontawesome/solid/cube +--- + +# Block Producer + +Block Producer is an optional service that assembles, signs, and submits blocks +when block production is enabled. A standard Koinos node can validate, +synchronize, and relay the chain without running this service. + +## Dependencies and inputs + +Block Producer connects to RabbitMQ and depends on: + +- Chain for head state, proposal validation, and block submission; +- Mempool for pending transactions and accepted-block processing; and +- P2P gossip status as a network-readiness input when that check is enabled. + +It also needs block-signing authority. Signing-key storage and producer +configuration are security-sensitive operator concerns, not Architecture +instructions. + +## Outputs and interfaces + +The service selects pending transactions, constructs a candidate block, asks +Chain to evaluate the proposal, signs a valid candidate, and submits it back to +Chain. The normal accepted-block path then notifies the rest of the node and +allows P2P to propagate the block. + +Block Producer does not make its own block canonical. The proposal still passes +through Chain validation and network fork choice. + +## State and consistency + +Block Producer does not own chain history. Its decisions depend on a current +Chain head, a compatible Mempool view, and adequate network information. A +running process therefore does not establish that it is eligible to produce or +that its blocks are being accepted. + +!!! warning "Production operations" + Do not use this page to configure production or signing keys. Follow the + reviewed [block production guide](../../nodes/block-production.md). + +## Versioned sources + +- [`koinos-block-producer` v1.3.1](https://github.com/koinos/koinos-block-producer/tree/8896d7aabbe9e0d154a5f7860920e95d17fd8cb4) +- [Chain proposal and submission schema in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/chain/chain_rpc.proto) +- [Current official Compose profile](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/docs/architecture/microservices/block-store.md b/docs/architecture/microservices/block-store.md index e69de29b..0fb044d1 100644 --- a/docs/architecture/microservices/block-store.md +++ b/docs/architecture/microservices/block-store.md @@ -0,0 +1,47 @@ +--- +icon: fontawesome/solid/database +--- + +# Block Store + +Block Store keeps durable copies of blocks and their receipts. It provides +historical block lookup without making the consensus state database serve as a +block archive. + +## Dependencies and inputs + +Block Store connects to RabbitMQ and consumes accepted-block information. In the +official Compose topology it starts after RabbitMQ and Chain. + +Its RPC interface supports reading blocks by ID or height, reading the highest +stored block, and adding a block to storage. + +## Outputs and interfaces + +P2P uses Block Store when serving blocks to peers and while coordinating block +synchronization. Account History can also read stored blocks while catching up. +API gateways can expose the lookup methods when Block Store is enabled. + +## State and consistency + +The selected release stores blocks, receipts, and lookup metadata in BadgerDB. +This is durable blockchain history, but storage does not make a block +canonical. Chain performs consensus validation and fork choice. + +The highest block in Block Store and the current Chain head can differ while a +service is starting or catching up. A historical query can therefore be behind +even when Chain itself is healthy. + +If Block Store is unavailable, the node can lose historical-query and +peer-serving capabilities, and services that rely on stored blocks may be +unable to catch up. + +!!! note "Operating the service" + Backup, restoration, reindexing, and storage checks are documented under + [Node Operators](../../nodes/index.md). + +## Versioned sources + +- [`koinos-block-store` v1.1.0](https://github.com/koinos/koinos-block-store/tree/2bb94558df61c71eb241002635444cdddce0843c) +- [Block Store RPC schema in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/block_store/block_store_rpc.proto) +- [Current official Compose relationship](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/docs/architecture/microservices/contract-meta-store.md b/docs/architecture/microservices/contract-meta-store.md index e69de29b..54d8b710 100644 --- a/docs/architecture/microservices/contract-meta-store.md +++ b/docs/architecture/microservices/contract-meta-store.md @@ -0,0 +1,40 @@ +--- +icon: fontawesome/solid/file-code +--- + +# Contract Meta Store + +Contract Meta Store builds a query index for metadata associated with deployed +smart contracts, including their Application Binary Interface (ABI). This lets +tools discover contract methods and types without making Chain maintain a +metadata-oriented index. + +## Dependencies and inputs + +The service connects to RabbitMQ, starts after Chain in the official Compose +topology, and consumes accepted-block information. It extracts relevant +contract metadata from the accepted chain data it processes. + +Its RPC interface provides contract metadata lookup by contract ID. + +## State and consistency + +The selected release stores its derived index in BadgerDB. The index can lag +Chain while catching up, and metadata observed on a recent accepted fork can +change if that fork is replaced. + +An ABI describes how tools can encode and decode a contract interface. Its +presence does not validate the contract or give the metadata independent +consensus authority. + +If Contract Meta Store is unavailable, contract metadata lookup fails, but +contract execution and Chain validation continue. + +See [Contract ABI](../contract-abi.md) for the format and its architectural +role. + +## Versioned sources + +- [`koinos-contract-meta-store` v1.1.0](https://github.com/koinos/koinos-contract-meta-store/tree/64e803e1db1a9bb2946ae379ddad0e5611442ec5) +- [Contract Meta Store RPC schema in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/contract_meta_store/contract_meta_store_rpc.proto) +- [Current official Compose relationship](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/docs/architecture/microservices/grpc.md b/docs/architecture/microservices/grpc.md index e69de29b..bc8c212f 100644 --- a/docs/architecture/microservices/grpc.md +++ b/docs/architecture/microservices/grpc.md @@ -0,0 +1,44 @@ +--- +icon: fontawesome/solid/tower-broadcast +--- + +# gRPC + +gRPC is the typed protobuf gateway to selected Koinos RPC services. Clients use +generated protobuf interfaces, while the gateway forwards each request through +RabbitMQ to the microservice that owns the method. + +## Dependencies and inputs + +The service depends on RabbitMQ, the public gRPC service definitions, and each +internal service required by an exposed method. The public schema contains a +selected API surface; it does not expose every internal RPC used inside the +node. + +## Outputs and interfaces + +gRPC returns typed protobuf responses and gRPC status errors. Depending on the +enabled services, its methods can query Chain, Block Store, Mempool, P2P, +Transaction Store, Contract Meta Store, and Account History. + +The gateway does not originate consensus decisions or maintain a second copy of +chain state. + +## State and consistency + +gRPC owns protocol and in-flight request state, not blockchain databases. A +reachable gRPC endpoint can still report that its target service is unavailable +or return data from an index that is catching up. + +Client and server schemas must be compatible. Retrying a read is different from +retrying a transaction or block submission after an uncertain timeout. + +!!! note "Public API operation" + Transport security, exposure, message limits, and health checks belong in + the [public API node guide](../../nodes/rpc-node.md). + +## Versioned sources + +- [`koinos-grpc` v1.1.1](https://github.com/koinos/koinos-grpc/tree/3a94c34fa002552ef586cd1af9bfd34d175430d3) +- [Public gRPC services in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/services.proto) +- [Current official Compose profile](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/docs/architecture/microservices/json-rpc.md b/docs/architecture/microservices/json-rpc.md index e69de29b..3e931de1 100644 --- a/docs/architecture/microservices/json-rpc.md +++ b/docs/architecture/microservices/json-rpc.md @@ -0,0 +1,45 @@ +--- +icon: fontawesome/solid/code +--- + +# JSON-RPC + +JSON-RPC is an HTTP gateway to Koinos microservices. It converts JSON-RPC +method names and JSON values into protobuf RPC messages, routes them through +RabbitMQ, and converts the response back to JSON. + +## Dependencies and inputs + +The gateway depends on RabbitMQ and on whichever internal service implements a +requested method. Chain is a declared startup dependency, while methods that +query blocks, pending transactions, account history, contract metadata, or +stored transactions require the corresponding optional service. + +The selected release loads protobuf descriptors and supports method allowlist +and denylist configuration. + +## Outputs and interfaces + +JSON-RPC exposes HTTP request and response semantics. It does not validate +blocks or transactions independently; submission methods are forwarded to +Chain, and read methods reflect the state of their target service. + +## State and consistency + +The gateway does not own chain or index databases. A reachable HTTP endpoint +can still return an internal-service error, and two read methods backed by +different services can reflect different catch-up positions. + +After a submission timeout, the gateway cannot by itself establish whether the +target completed the request. Clients should use method-specific retry and +lookup behavior. + +!!! note "Public API operation" + Network exposure, TLS, proxies, request limits, and health checks belong in + the [public API node guide](../../nodes/rpc-node.md). + +## Versioned sources + +- [`koinos-jsonrpc` v1.2.0](https://github.com/koinos/koinos-jsonrpc/tree/2c9433c67f2f60c920525a6c4bd3e15b0b51d94a) +- [Public RPC descriptors shipped by the official bundle](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/config-example/koinos_descriptors.pb) +- [Current official Compose profile](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/docs/architecture/microservices/koinos-chain.md b/docs/architecture/microservices/koinos-chain.md index e69de29b..032e62fb 100644 --- a/docs/architecture/microservices/koinos-chain.md +++ b/docs/architecture/microservices/koinos-chain.md @@ -0,0 +1,56 @@ +--- +icon: fontawesome/solid/link +--- + +# Chain + +Chain is the consensus and execution service of a Koinos node. It validates +transactions and blocks, executes smart contracts, applies fork-choice rules, +and maintains the blockchain state used to validate the next block. + +Other services store artifacts or build indexes, but Chain is the service that +decides whether a transaction or block is valid in the local node. + +## Dependencies and inputs + +Chain connects to RabbitMQ for internal RPC and broadcasts. Its main inputs are: + +- transactions submitted by API services or received from peers; +- blocks received by P2P or created by Block Producer; +- the node's existing chain state; and +- the protocol rules, system calls, and system contracts active at that block. + +Chain also queries Block Store and Mempool while catching up and coordinating +state with the rest of the node. + +## Outputs and interfaces + +Chain provides RPC methods for submitting blocks and transactions and for +reading state such as the chain ID, head block, fork heads, account nonce, +resource credits, resource limits, and contract results. + +After processing data, it broadcasts events such as accepted blocks, +irreversible blocks, fork heads, accepted or failed transactions, and smart +contract events. These broadcasts let other services update without polling +Chain continuously. + +## State and consistency + +Chain stores consensus-critical state in a RocksDB-backed state database. +Accepted blocks are not necessarily irreversible: a competing fork can replace +recent accepted blocks. Services that build derived data must therefore follow +both fork changes and irreversible-block notifications. + +If Chain is unavailable, the node cannot validate new network data or answer +authoritative state queries. An API process may still be reachable while its +Chain dependency is unavailable or behind. + +!!! note "Operating the service" + Data directories, synchronization, recovery, and health checks belong in + [Node Operators](../../nodes/index.md). + +## Versioned sources + +- [`koinos-chain` v1.5.2](https://github.com/koinos/koinos-chain/tree/0ae99eced8b585c4145424e9c2a28f667796cc66) +- [Chain RPC schema in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/chain/chain_rpc.proto) +- [Current official Compose relationship](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/docs/architecture/microservices/mempool.md b/docs/architecture/microservices/mempool.md index e69de29b..3999b8bc 100644 --- a/docs/architecture/microservices/mempool.md +++ b/docs/architecture/microservices/mempool.md @@ -0,0 +1,44 @@ +--- +icon: fontawesome/solid/layer-group +--- + +# Mempool + +Mempool maintains the node's working set of pending transactions. It tracks the +nonces and resource credits reserved by those transactions and supplies +candidate transactions to Block Producer. + +A transaction in Mempool has not been included in the canonical chain. + +## Dependencies and inputs + +Mempool connects to RabbitMQ and coordinates with Chain. It observes: + +- transactions accepted or rejected during validation; +- accepted blocks that may include pending transactions or change their + validity; and +- irreversible blocks that allow old fork state to be discarded. + +## Outputs and interfaces + +Its RPC interface provides pending-transaction lookup, pending counts, account +nonce checks, and reserved resource-credit information. After accepting a +pending transaction, Mempool broadcasts that updated view. It also forwards a +processed accepted-block event used by Block Producer. + +## State and consistency + +The selected release uses a fork-aware Koinos state database for working state. +Mempool state is transient relative to the blockchain: transactions can be +included, invalidated by a state change, displaced by a fork, expire, or be +removed under service policy. + +Consequently, finding a transaction in Mempool does not guarantee inclusion in +a block. If Mempool is unavailable, transaction queries and block assembly are +affected even though Chain can continue validating blocks received from peers. + +## Versioned sources + +- [`koinos-mempool` v1.5.0](https://github.com/koinos/koinos-mempool/tree/3f2a276e4b3e4fa37c69031b2f6f707915644086) +- [Mempool RPC schema in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/mempool/mempool_rpc.proto) +- [Current official Compose relationship](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/docs/architecture/microservices/p2p.md b/docs/architecture/microservices/p2p.md index e69de29b..069a645b 100644 --- a/docs/architecture/microservices/p2p.md +++ b/docs/architecture/microservices/p2p.md @@ -0,0 +1,51 @@ +--- +icon: fontawesome/solid/share-nodes +--- + +# P2P + +P2P connects one Koinos node to other Koinos nodes. It discovers and manages +peers, exchanges transactions and blocks, and coordinates synchronization with +the network. + +RabbitMQ connects services inside one node. P2P is the separate interface +between nodes. + +## Dependencies and inputs + +P2P uses: + +- Chain for the chain ID, head and fork information, and validation of received + transactions and blocks; +- Block Store when retrieving blocks to serve or synchronize; +- RabbitMQ for communication with local services; and +- libp2p protocols for connections and gossip with remote peers. + +The peer protocol includes operations for comparing chain information and +retrieving blocks. Data received from a peer is never accepted solely because a +peer supplied it; P2P submits it to Chain for local validation. + +## Outputs and interfaces + +P2P announces locally accepted transactions and blocks to peers and forwards +received network data into the local node. It also provides a gossip-status RPC +and broadcasts gossip status for services such as Block Producer. + +## State and consistency + +P2P does not own canonical blockchain state. Peer-reported head information is +an observation used for synchronization, not a local consensus decision. + +If P2P is unavailable or has no compatible connected peers, local services can +remain healthy while the node stops receiving new network data. Synchronization +also depends on Chain and Block Store making progress. + +!!! note "Operating the service" + Peer addresses, ports, identity files, and connectivity checks belong in + [Node Operators](../../nodes/index.md). + +## Versioned sources + +- [`koinos-p2p` v1.3.0](https://github.com/koinos/koinos-p2p/tree/e2267ba230960b5e4100c16ad84c42cfc12eec4b) +- [P2P RPC schema in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/p2p/p2p_rpc.proto) +- [Current official Compose relationship](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/docs/architecture/microservices/rest.md b/docs/architecture/microservices/rest.md new file mode 100644 index 00000000..56759dfd --- /dev/null +++ b/docs/architecture/microservices/rest.md @@ -0,0 +1,48 @@ +--- +icon: fontawesome/solid/globe +--- + +# REST + +REST provides resource-oriented HTTP endpoints, an OpenAPI description, and a +browser-accessible API reference for selected Koinos capabilities. + +In the selected official Compose release, REST calls JSON-RPC rather than +connecting directly to RabbitMQ. + +## Dependencies and inputs + +The service accepts HTTP requests and uses JSON-RPC as its upstream Koinos +provider. Each endpoint therefore also depends on the internal service used by +the underlying JSON-RPC method. + +The implementation includes application-level response transformation, +contract ABI data, and optional cache-related components. None of those layers +replaces Chain or an authoritative service. + +## Outputs and interfaces + +REST returns HTTP responses and publishes an OpenAPI/Swagger description of its +endpoints. It translates higher-level endpoint behavior into one or more +JSON-RPC calls. + +## State and consistency + +REST does not own canonical blockchain state. Its availability and freshness +depend on JSON-RPC and the downstream services reached by each endpoint. +Application-level transformation or caching can have different freshness +semantics from the Chain head. + +The OpenAPI document and runtime must come from the same release so client +expectations do not drift from implemented behavior. + +!!! note "Using and operating REST" + Application examples belong in [Interacting with Koinos](../../interacting/rest-api.md). + Public exposure and health checks belong in + [Node Operators](../../nodes/rpc-node.md). + +## Versioned sources + +- [`koinos-rest` v1.1.1](https://github.com/koinos/koinos-rest/tree/d7f5bc90f11f78af9167e64913a028c00036d134) +- [`koinos-jsonrpc` v1.2.0 upstream](https://github.com/koinos/koinos-jsonrpc/tree/2c9433c67f2f60c920525a6c4bd3e15b0b51d94a) +- [Current official Compose relationship](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/docs/architecture/microservices/transaction-store.md b/docs/architecture/microservices/transaction-store.md index e69de29b..d7bfa0f4 100644 --- a/docs/architecture/microservices/transaction-store.md +++ b/docs/architecture/microservices/transaction-store.md @@ -0,0 +1,36 @@ +--- +icon: fontawesome/solid/receipt +--- + +# Transaction Store + +Transaction Store builds a lookup index for transactions found in accepted +blocks. It lets clients retrieve transaction and block context by transaction +ID without placing that query index in Chain. + +## Dependencies and inputs + +Transaction Store connects to RabbitMQ, starts after Chain in the official +Compose topology, and consumes accepted-block data. + +Its RPC interface provides transaction lookup by ID. API gateways can expose +that method when the service is running. + +## State and consistency + +The selected release stores the derived index in BadgerDB. It is not the source +of consensus truth and can be behind Chain while it processes blocks. + +Because recent accepted blocks can be replaced by a fork, the index must keep +its view consistent with accepted chain history. A transaction lookup that +returns no result should not be interpreted as proof that the transaction never +existed; the service may be disabled, unavailable, or catching up. + +If Transaction Store is unavailable, transaction-by-ID queries fail, but Chain +validation does not depend on that derived index. + +## Versioned sources + +- [`koinos-transaction-store` v1.1.0](https://github.com/koinos/koinos-transaction-store/tree/c8d985ab1b0dd3862fd2d0099f4458ebc6e0920c) +- [Transaction Store RPC schema in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/transaction_store/transaction_store_rpc.proto) +- [Current official Compose relationship](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/docs/architecture/proof-of-burn.md b/docs/architecture/proof-of-burn.md index b9d9e0dd..c45c13ab 100644 --- a/docs/architecture/proof-of-burn.md +++ b/docs/architecture/proof-of-burn.md @@ -2,152 +2,76 @@ icon: fontawesome/solid/fire --- -# Proof-of-Burn -Koinos' Proof-of-Burn (PoB) algorithm is designed to be a fair and efficient consensus mechanism. In this system, participants "burn" tokens, thereby demonstrating their commitment and reducing the circulating supply of the token. To determine block validators, participants submit cryptographic proofs. Validators are selected randomly based on the size of the burn relative to the total amount burned within a specific time window, ensuring that larger burns have a higher chance of being selected. This mechanism incentivizes participants to contribute to the network's security and stability by sacrificing tokens, with the potential reward of becoming block validators and earning block rewards in return. The Proof-of-Burn concept aligns with Koinos' aim to create a fair and sustainable blockchain ecosystem. - ---- -## Consensus in a smart contract -At genesis Koinos mainnet did not include any smart contracts. The base implementation was federated and the genesis key had sole ability to produce blocks. Within a handful of blocks, smart contracts that give Koinos its functionality were uploaded. One of those smart contracts was the [Proof-of-Burn consensus algorithm](https://github.com/koinos/koinos-contracts-as/blob/master/contracts/pob/assembly/Pob.ts). - -All system smart contracts can be found on GitHub under the [Koinos organization](https://github.com/koinos). Those that are implemented with AssemblyScript can be found in the [Koinos Contract AS repository](https://github.com/koinos/koinos-contracts-as). While those that are implemented in C++ can be found in the [Koinos Contract CPP respository](https://github.com/koinos/koinos-contracts-cpp). The Proof-of-Burn consensus is implemented using AssemblyScript. - -[Read the PoB smart contract »](https://github.com/koinos/koinos-contracts-as/blob/master/contracts/pob/assembly/Pob.ts) - ---- -## Vocabulary terms -To better understand the following sections it may be helpful to define some vocabulary terms. - -_**Table 1.** A table containing commonly used vocabulary terms when discussiong Koinos' consensus algorithm._ - -| Term | Definition | -| --- | --- | -| VHP | VHP is an acronym and a token ticker for Virtual Hash Power. It is a representation of block production power and is analagous to hashrate in Proof-of-Work consensus algorithms. | -| Effective VHP | The amount of VHP that should be accounted for with regard to consensus operations. Effective VHP is equal to your VHP balance after 20 blocks. | -| Virtual supply | This is defined as total KOIN supply + total VHP supply. | -| VRF | This is an acronym for Verifiable Random Function. It is used to generate a random number that is cryptographically verified as random. | -| Hot wallet | A hot wallet is often used for convenience and usability reasons, the keys are stored and used on a machine that is actively connected to the internet. | -| Producer address | The account that holds both KOIN and VHP for use during block production. | - ---- -## The Proof-of-Burn contract ABI -Because the consensus algorithm (PoB) is implemented as a smart contract, interacting with it is accomplished through normal smart contract calls. Like all other smart contracts it has an Application Binary Interface or ABI. - -```proto linenums="1" title="pob.abi" -{ - "methods" : { - "burn": { - "argument" : "koinos.contracts.pob.burn_arguments", - "return" : "koinos.contracts.pob.burn_result", - "entry-point" : "0x859facc5", - "description" : "Burns KOIN to receive VHP", - "read-only" : false - }, - "register_public_key": { - "argument" : "koinos.contracts.pob.register_public_key_arguments", - "return" : "koinos.contracts.pob.register_public_key_result", - "entry-point" : "0x53192be1", - "description" : "Registers a block production public key to an address", - "read-only" : false - }, - "get_public_key": { - "argument" : "koinos.contracts.pob.get_public_key_arguments", - "return" : "koinos.contracts.pob.get_public_key_result", - "entry-point" : "0x96634f68", - "description" : "Gets the public key registered to a producer address", - "read-only" : true - }, - "get_metadata": { - "argument" : "koinos.contracts.pob.get_metadata_arguments", - "return" : "koinos.contracts.pob.get_metadata_result", - "entry-point" : "0xfcf7a68f", - "description" : "Returns the PoB metadata", - "read-only" : true - }, - "get_consensus_parameters": { - "argument" : "koinos.contracts.pob.get_consensus_parameters_arguments", - "return" : "koinos.contracts.pob.get_consensus_parameters_result", - "entry-point" : "0x5fd7ac0f", - "description" : "Returns the PoB consensus parameters", - "read-only" : true - }, - "update_consensus_parameters": { - "argument" : "koinos.contracts.pob.update_consensus_parameters_arguments", - "return" : "koinos.contracts.pob.update_consensus_parameters_result", - "entry-point" : "0x793e7c30", - "description" : "Updates the PoB consensus parameters", - "read-only" : false - } - }, - "types" : "CpQNCh5rb2lub3MvY29udHJhY3RzL3BvYi9wb2IucHJvdG8SFGtvaW5vcy5jb250cmFjdHMucG9iGhRrb2lub3Mvb3B0aW9ucy5wcm90byLiAQoUY29uc2Vuc3VzX3BhcmFtZXRlcnMSPwocdGFyZ2V0X2FubnVhbF9pbmZsYXRpb25fcmF0ZRgBIAEoDVIZdGFyZ2V0QW5udWFsSW5mbGF0aW9uUmF0ZRIuChN0YXJnZXRfYnVybl9wZXJjZW50GAIgASgNUhF0YXJnZXRCdXJuUGVyY2VudBIyChV0YXJnZXRfYmxvY2tfaW50ZXJ2YWwYAyABKA1SE3RhcmdldEJsb2NrSW50ZXJ2YWwSJQoOcXVhbnR1bV9sZW5ndGgYBCABKA1SDXF1YW50dW1MZW5ndGgiZgoRcHVibGljX2tleV9yZWNvcmQSIwoKcHVibGljX2tleRgBIAEoDEIEgLUYAFIJcHVibGljS2V5EiwKEHNldF9ibG9ja19oZWlnaHQYAiABKARCAjABUg5zZXRCbG9ja0hlaWdodCJ2CghtZXRhZGF0YRIYCgRzZWVkGAEgASgMQgSAtRgAUgRzZWVkEiQKCmRpZmZpY3VsdHkYAiABKAxCBIC1GABSCmRpZmZpY3VsdHkSKgoPbGFzdF9ibG9ja190aW1lGAMgASgEQgIwAVINbGFzdEJsb2NrVGltZSJ4Cg5zaWduYXR1cmVfZGF0YRIhCgl2cmZfcHJvb2YYASABKAxCBIC1GABSCHZyZlByb29mEh8KCHZyZl9oYXNoGAIgASgMQgSAtRgAUgd2cmZIYXNoEiIKCXNpZ25hdHVyZRgDIAEoDEIEgLUYAFIJc2lnbmF0dXJlIkoKC3ZyZl9wYXlsb2FkEhgKBHNlZWQYASABKAxCBIC1GABSBHNlZWQSIQoKYmxvY2tfdGltZRgCIAEoBEICMAFSCWJsb2NrVGltZSJmCh1yZWdpc3Rlcl9wdWJsaWNfa2V5X2FyZ3VtZW50cxIgCghwcm9kdWNlchgBIAEoDEIEgLUYBlIIcHJvZHVjZXISIwoKcHVibGljX2tleRgCIAEoDEIEgLUYAFIJcHVibGljS2V5IhwKGnJlZ2lzdGVyX3B1YmxpY19rZXlfcmVzdWx0IocBCg5idXJuX2FyZ3VtZW50cxIlCgx0b2tlbl9hbW91bnQYASABKARCAjABUgt0b2tlbkFtb3VudBInCgxidXJuX2FkZHJlc3MYAiABKAxCBIC1GAZSC2J1cm5BZGRyZXNzEiUKC3ZocF9hZGRyZXNzGAMgASgMQgSAtRgGUgp2aHBBZGRyZXNzIg0KC2J1cm5fcmVzdWx0IiQKImdldF9jb25zZW5zdXNfcGFyYW1ldGVyc19hcmd1bWVudHMiYwofZ2V0X2NvbnNlbnN1c19wYXJhbWV0ZXJzX3Jlc3VsdBJACgV2YWx1ZRgBIAEoCzIqLmtvaW5vcy5jb250cmFjdHMucG9iLmNvbnNlbnN1c19wYXJhbWV0ZXJzUgV2YWx1ZSIYChZnZXRfbWV0YWRhdGFfYXJndW1lbnRzIksKE2dldF9tZXRhZGF0YV9yZXN1bHQSNAoFdmFsdWUYASABKAsyHi5rb2lub3MuY29udHJhY3RzLnBvYi5tZXRhZGF0YVIFdmFsdWUiYAoZcmVnaXN0ZXJfcHVibGljX2tleV9ldmVudBIeCgdhZGRyZXNzGAEgASgMQgSAtRgGUgdhZGRyZXNzEiMKCnB1YmxpY19rZXkYAiABKAxCBIC1GABSCXB1YmxpY0tleSI8ChhnZXRfcHVibGljX2tleV9hcmd1bWVudHMSIAoIcHJvZHVjZXIYASABKAxCBIC1GAZSCHByb2R1Y2VyIjMKFWdldF9wdWJsaWNfa2V5X3Jlc3VsdBIaCgV2YWx1ZRgBIAEoDEIEgLUYAFIFdmFsdWUiaQoldXBkYXRlX2NvbnNlbnN1c19wYXJhbWV0ZXJzX2FyZ3VtZW50cxJACgV2YWx1ZRgBIAEoCzIqLmtvaW5vcy5jb250cmFjdHMucG9iLmNvbnNlbnN1c19wYXJhbWV0ZXJzUgV2YWx1ZSIkCiJ1cGRhdGVfY29uc2Vuc3VzX3BhcmFtZXRlcnNfcmVzdWx0QjxaOmdpdGh1Yi5jb20va29pbm9zL2tvaW5vcy1wcm90by1nb2xhbmcva29pbm9zL2NvbnRyYWN0cy9wb2JiBnByb3RvMw==" -} +# Proof of Burn + +Koinos uses Proof of Burn (PoB) to select and validate block production. +Participants permanently burn KOIN through the PoB system contract and receive +Virtual Hash Power (VHP). VHP represents production power; it is not ordinary +spendable KOIN. + +Burning KOIN is an irreversible transaction. This architecture page explains +the relationship without providing executable burn or producer-registration +instructions. + +## From KOIN to effective VHP + +The PoB contract burns KOIN and mints the corresponding amount of VHP. The VHP +contract tracks both the token balance and the amount considered **effective** +for consensus. + +Transfers of VHP are subject to an effectiveness delay. This prevents the same +production power from being moved rapidly between accounts and counted more +than intended. + +## Block eligibility + +For each production opportunity, Block Producer obtains current consensus +metadata from Chain and creates a verifiable random function (VRF) proof. The +protocol evaluates that proof using the producer's effective VHP and the current +difficulty. + +More effective VHP increases the probability of satisfying the target, but it +does not reserve a deterministic sequence of blocks. A candidate that satisfies +the production condition is still submitted to Chain and must pass normal block +validation. + +```mermaid +flowchart TB + KOIN["KOIN"] -- "irreversible burn" --> VHP["VHP"] + VHP --> Effective["Effective VHP"] + Metadata["Consensus metadata"] --> Proof["VRF proof and target check"] + Effective --> Proof + Proof --> Candidate["Candidate block"] + Candidate --> Chain["Chain validation and fork choice"] ``` -Let us elaborate on all entry points provided by the PoB contract. - -_**Table 2.** A table containing descriptions of entry points on the Proof-of-burn contract.._ - -|
Entry point
| Description | -| --- | --- | -| `burn` | This method allows an account to burn their KOIN and receive VHP in return. The system always provides a 1:1 exchange from KOIN to VHP. | -| `register_public_key` | For security purposes, the account that holds value (in VHP and KOIN) and different from the private key used to sign blocks. This method allows an account to associate their "producer address" with the keys that will sign blocks and therefore be a hot wallet. | -| `get_public_key` | A simple read method that allows a user to see what public key is associated with a particular producer address. | -| `get_metadata` | This method is used to retrieve current consensus metadata which includes the current difficulty, seed, and the last block time. | -| `get_consensus_parameters` | This read method retrieves the currently active consensus parameters. It includes the target annual inflation, the target burn percentage, target block time, and the quantum length. | -| `update_consensus_parameters` | This method allows the consensus parameters to be updated. Currently this can only occur through the governance process. | +## VHP consumption and replenishment ---- -## Block production -In many ways PoB works very similar to Proof-of-Work (PoW). Like PoW, there is a constantly adjusting difficulty. The more VHP that produces on the network, the more difficult it is to produce a valid block. The difficulty adjustment algorithm is borrowed from Ethereum's PoW implementation verbatim. - -### Calculating the difficulty target -The target difficulty can be calculated by retrieving the current difficulty from calling the `get_metadata` entry point converting it to a `uint128` and using it as the denominator with the maximum value of a `uint128` as the numerator. +Successful production consumes a protocol-calculated amount of VHP. A producer +therefore cannot assume that one initial KOIN burn provides permanent production +capacity. Producers may need to replenish VHP over time to maintain their +intended production power. -Simpy put the `target` can be defined as `max(uint128) / difficulty`. +Consensus parameters and current balances are on-chain state and can change. +Architecture documentation should not embed historical burn amounts, +difficulty values, inflation percentages, or expected returns. -### Determining if a block has met the target difficulty -Using the seed from `get_metadata` along with the current block time, block producers use a VRF (verifiable random function) to generate a proof and a proof hash. Using the proof hash, we then right bitshift it by 128 and divide that number by current effective VHP balance of the producer address. If that value is under the difficulty target, we consider the difficulty met and the block can be considered valid. +## Separation of responsibilities -This can be understood simply with `(proof_hash >> 128) / vhp_balance < target`. - ---- -## Effective VHP -To prevent certain abuses, using the same VHP to produce with different accounts in order to gain an advantage, we introduce the concept of effective VHP. When VHP is moved there is a block delay before it becomes "effective". The block window where VHP becomes effective is 20 blocks. This implementation can be found in the VHP contract itself. +- The PoB and VHP system contracts implement the consensus-specific token and + eligibility rules. +- Block Producer constructs proofs and candidate blocks. +- Chain validates the proof, executes the block, and applies fork choice. +- P2P propagates accepted blocks to other nodes. -[Read the VHP contract »](https://github.com/koinos/koinos-contracts-as/blob/master/contracts/vhp/assembly/Vhp.ts) +Producer keys, public-key registration, VHP acquisition, resource readiness, +and monitoring belong in the reviewed +[block production guide](../nodes/block-production.md). Privileged contract +details belong in [System Contracts](../system-contracts/proof-of-burn.md). ---- -## Target burn percentage and annual inflation -Let's begin with some real world numbers. The current mainnet target annual inflation is 2% and the target burn percentage is 50.1%. This means that if the target burn percentage is met the annual inflation will work out to 2% of the current total virtual supply. The yield of a block producer would also be 2% annually. - -### What happens if the target burn percentage is not met? -If we are under the target burn percentage we have the same annual inflation but there is less VHP producing. This effective increases the return of block production. The system innately incentivizes more block producers to hop on the network and contribute to network security. - -### What happens if we exceed the target burn percentage? -If we are over the target burn percentage, again, we have the same annual inflation but there is more VHP producing. This will decrease the return of block production. This state effectively discourages block producers to operate creating an economic downward pressure on creating new VHP for block production. - ---- -## The actual target annual inflation -Because new KOIN is being minted every block and we target 2% annual inflation, we must account for a compounding effect. We use the following equation to set the annual inflation within the smart contract. - -Where: -``` -x = target annual inflation -y = block per year -z = desired inflation rate -``` - -The actual target inflation can be expressed as: `x = y*((1 + z)^(1 / y) - 1)` - -Therefore, technically the target annual inflation is set to 1.9802%, which is effectively 2% when considering the compounding effect of newly minted KOIN over the year. - ---- -## Block producer security -Having an account with large amounts of VHP and KOIN is considered valuable and should be kept secure. It is always recommended to keep your cryptocurrency secure and to achieve this you should avoid keeping your assets in a hot wallet. Because of this reality, we introduce the public key pairing in our consensus algorithm. You may associate a hot public/private key pairing with your producer address in order to safeguard your assets. - -In other words, the safest way to produce blocks is to keep your producer address in cold storage and your block producer key pair hot. See the `register_public_key` entry point for more information on this topic. - ---- -## Block resources -As you may know already, every bit of computation, disk, and storage is paid for on Koinos through a user's mana. However, there is additional processing on the blockchain that occurs outside of transactions when processing a block. Like transactions, this is also paid for by the user. Unlike normal transactions, this cost is paid for by the block producer. +## Versioned sources -Because the costs of processing a block is paid for by the block producer, it is necessary for the producer address to contain both VHP and KOIN. The block producer must maintain enough KOIN in order to meet the mana requirements for submitting a block in additional to having enough VHP to meet the target difficulty. \ No newline at end of file +- [PoB contract reference implementation](https://github.com/koinos/koinos-contracts-as/blob/aef57bdb8a5960ec2b799ee0f17bf7a25bb5de85/contracts/pob/assembly/Pob.ts) +- [VHP contract reference implementation](https://github.com/koinos/koinos-contracts-as/blob/aef57bdb8a5960ec2b799ee0f17bf7a25bb5de85/contracts/vhp/assembly/Vhp.ts) +- [`koinos-block-producer` v1.3.1](https://github.com/koinos/koinos-block-producer/tree/8896d7aabbe9e0d154a5f7860920e95d17fd8cb4) +- [PoB and VHP schemas in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/tree/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/contracts) diff --git a/docs/architecture/resources.md b/docs/architecture/resources.md index 2fe784c9..4360e1f5 100644 --- a/docs/architecture/resources.md +++ b/docs/architecture/resources.md @@ -3,172 +3,72 @@ icon: fontawesome/solid/microchip --- # Resources -Koinos manages resources using a combination of automated resource markets. Every transaction consumes three resources in different amounts. Those resources are: -1. Compute bandwidth -2. Network bandwidth -3. Disk storage +Koinos limits blockchain work through Resource Credits (RC) rather than a +conventional per-transaction gas fee. Transactions consume measurable +resources, and the protocol checks both the payer's available RC and the +remaining capacity of the block. -Compute bandwidth measures the computational resources required to execute a transaction. These are primarily consumed by the smart contracts called by the transaction, but also by the system calls those smart contracts use as well as basic computation to authorize the transaction prior to execution of smart contracts. Compute resources must be measured and limited to prevent unlimited contract execution (e.g. infinite loops). +On mainnet, wallets commonly present an account's available RC as **mana**. Mana +is recoverable transaction capacity associated with KOIN; spending it does not +transfer KOIN to a block producer as a gas payment. -Network bandwidth measures of the wire size of the transaction itself using the canonical Protobuf serialization. Network bandwidth must be limited to ensure responsiveness of the p2p network. +## Resource types -Disk storage measures how much state a transaction consumes upon execution. All persistent state of a smart contract is written to disk on a node. Disk storage is limited to prevent a smart contract from consuming all available storage of the system running a node. +Koinos accounts for three resources: ---- -## Resource market makers -The Koinos Blockchain Framework (KBF) costs resources in Resource Credits, or RC. On the Koinos mainnet RC is convertible to Mana 1:1 and can be thought of as the exact same thing. But the KBF itself is designed to support any resource system and so RC could be bought using a fee at a different rate. This guide will use the RC terminology to match the internal documentation of the KBF, but you can use Mana and RC interchangeably. +| Resource | What it measures | Why it is limited | +| --- | --- | --- | +| Compute bandwidth | Contract execution, authorization, system calls, and other processing | Prevents unbounded execution | +| Network bandwidth | Canonically encoded transaction data carried by the network | Keeps blocks and peer traffic bounded | +| Disk storage | Persistent state created or changed by execution | Limits long-term node storage growth | -Every resource has an internal market for pricing each resource. On one side of the market is the resource and on the other is a pool of RC. The internal mechanism is an XYK market maker, as popularized by Uniswap and other similar DEXs. The XYK market maker was chosen for a few reasons. +A transaction can use all three in different proportions. -1. The implementation is simple and efficient -2. The price curve is smooth -3. Changes in price are predictable +## Account Resource Credits -When a transaction is applied, each resource is tallied and priced, and the payer for the transaction is charged for each resource. If a resource costs cannot be paid, the transaction is reverted and the payer is charged for the amount up until the reversion. +Before committing a transaction, Chain determines the account responsible for +its resources and reads that account's available RC. Authorization and payer +semantics can make the payer different from the account that submitted or +signed another part of the transaction. -The price for resources is constant each block. Each block has a maximum number of resources that can be used in that block. The price for the resource on a block is the average price for the resource assuming the maximum of that resource is used for the block. This ensures that a) the resource is always paid for completely (avoid rounding down) and b) each transaction pays the same price for resources, removing advantages for transactions being applied earlier in the block. +The transaction must remain within the available RC calculated for its +execution. The exact mana regeneration rules and payer behavior are implemented +by system contracts and can evolve through governance. -A challenge unique to Koinos is the need to choose a value for `k`. In a DEX, `k` is a result of the liquidity added by liquidity providers. Because the resource markets are internal and able to be directly interacted with, the implementation must choose a value, or values, for `k` depending on different situations. +## Block resource limits ---- -## Derivation of k -Before deriving a value of `k`, we need a few definitions. +Each block also has compute, network, and disk limits. These bounds protect the +network even when an individual payer has enough RC. -- `p` is the resource pool -- `r` is the rc reserve -- `B` is the block budget of new resources -- `d` is the decay percent (the percent of the resource pool the decays each block to limit how large the resource pool can become) -- `u` is the resources used on the block -- `S` is the current supply of KOIN +The resources system contract maintains resource markets used to calculate the +current limits and RC cost for each resource. Usage changes the market state +from block to block, so applications should query current limits instead of +embedding fixed values. -The basic equation of the market maker is: +Block processing also has resource costs outside ordinary transactions. A block +producer must satisfy the production and resource requirements for its block; +having VHP alone is not the complete readiness condition. +```mermaid +flowchart TB + Transaction --> Meter["Measure compute, network, disk"] + Meter --> Account{"Enough payer RC?"} + Account -- "No" --> Reject["Execution cannot succeed"] + Account -- "Yes" --> Block{"Within block limits?"} + Block -- "No" --> Reject + Block -- "Yes" --> Apply["Apply transaction state"] ``` -p * r = k -``` - -Every block we decay, mint, and consume resources. The equation for this process at equilibrium is: - -``` -(d * p) + B - u = p -``` - -We first decay based on the decay percent, then we add the resources for the block budget and then we subtract how many were used. What equation means is that for a constant `d` and `B`, for any given usage, `u`, there is an equilibrium resource pool, `P`, that `p` will approach. This is an important behavior as it means there will be a specific price for a specific usage level. This fact will be used later on when we solve the parameterization of `k`. `t` is the number of tokens required to purchase the resources. - -When we consume resources and charge rc, it will solve the equation: - -``` -(p - u) * (r + t) = k -``` - -Using the second equation, we can solve for `p`: - -``` - (d * p) + B - u = p - B - u = p - (d * p) - B - u = p * (1 - d) -(B - u) / (1 - d) = p -``` - -From the first equation, we also have that: -``` -r = k / p -``` - -Now, using the third equation, we can solve for `k`: - -``` - (p - u) * (r + S) = k - (p - u) * ((k / p) + S) = k -k + (p * S) - (u * k / p) - (u * S) = k - (p * S) - (u * S) = u * k / p - S * (p - u) = u * k / p - S * (p / u) * (p - u) = k -``` - -While this equation is a bit complicated, it is important because it means that we have a way to calculate `k` in terms of `B`, `u`, `d`, and `S`. This is important because none of these values are defined by the current state of the market maker, but based on other factors. `B`, `u`, and `d` and configured, and `S` is from the state of KOIN. - ---- -## Value of `u` -Consider the decay equation: - -``` -(d * p) + B - u = p -``` - -We have the block budget `B` coming in, decay percent `d` going out, and usage `u` going out. At equilibrium, the budget coming in must be equal to the decay and the usage. - -``` -(1 - d) * p + u = B -``` +## Architecture versus operation -This means that the block budget must always be above the usage (or else the decay term is 0 or `p` is 0). We can therefore bound `u` between 0 and B. +This page describes the accounting boundary. Current values, monitoring, +capacity planning, and producer checks belong in +[Node Operators](../nodes/index.md). Privileged resource-contract behavior +belongs in [System Contracts](../system-contracts/resources.md). -When `u` is close to 0, the decay term must be larger, therefore `p` must be larger, and therefore there is more price elasticity. Conversely, when `u` is close to `B`, the decay term must be smaller, `p` must be smaller, and there is less price elasticity. +## Versioned sources ---- -## Value for `d` -`d` is the decay percent to estimate the exponential decay each block. Our decay term also affects the pool size, similarly to `u`. But it also has the practical effect of changing the maximum and minimum resource pool sizes (by consequence the maximum and minimum price for a resource) and how quickly the pool goes from one price to another when usage changes. - -In practical testing, a three day half life seemed to have a good balance of responsiveness to price moves in both directions, without being too unpredictable. Solving for `d` becomes simple. - -There is a block produced every three seconds, on average, and after three days we want the resource pool to half the size. There are 86400 blocks produced, on average, every three days. We just need to solve the following equation: - -``` -d ^ 86400 = 0.5 -86400 * ln( d ) = ln( 0.5 ) -ln( d ) = ln( 0.5 ) / 86400 -d = 0.5 ^ (1 / 86400) -``` - -The value of `d` is 0.99999197750. - ---- -## Budget premium -Looking at our above equation, it becomes clear that the usage `u` cannot equal the budget `B` unless the decay rate is close to 1, or the resource pool `p` is 0. For this reason the budget `B` must be larger than intended so that `u` can be equal to `B` and the equation has stability. This new factor will be called the budget premium, denoted by `m`. Our equilibrium equation now becomes: - -``` -(1 - d) * p + u = B * m -``` - -We want to fix the case when usage is at 100%. The amount printed in the budget needs to equal the downward force of both the decay rate and the usage. - -``` - (1 - d) * p_100 + B = B * m -(1 - d) * p_100 / B + 1 = m -``` - ---- -## Fractional reserve constraints -One way to think about the resource prices curves is as a fractional reserve system. When we are at 100% resource usage, we want to be at 100% Mana usage. Or, put another way, Mana always grants you a percentage of the resources, but when there is low demand, you can access more than your share. - -At 100% usage the price of a resource should be proportional to the budget divided by the token supply. - -The general price formula for any purchase of resources is: - -``` -u / t = B / S -``` - -More specifically, the budget's worth of resources over the Mana regeneration period, in blocks. Mana regenerates over 5 days and the block interval is 3 seconds per block, so the number of blocks in the Mana regeneration period is `86400 * 5 / 3` or `144000`. We also have three resources, so we need to cut the token supply in third. Furthermore, at 100% usage, the usage is equal to the budget (`u = B`). - -The actual equation we care about is: - -``` -B / t_100 = (B * 144000) / (S / 3) -B / t_100 = B * 432000 / S -1 / t_100 = 432000 / S - t_100 = S / 432000 -``` - -We need one other point to fix that will set the curve. For this purpose, we chose 50% usage. The amount of resources needed to access 50% of the resources should be less than 50% to ensure a fractional reserve system. If the value is too low then there will be massive resource price increases as usage approaches 100%. If the value is too high, then there isn't enough incentive for surplus resources to be used. The choice of this value is more art than science. We chose 10% as a good number, meaning 10% of the token supply can access 50% of the resources. We can construct a similar equation to the one above with this parameterization. - -``` -(B / 2) / t_50 = (B * 144000) / (S / (3 * 5)) -(B / 2) / t_50 = (B * 2160000) / S - B / t_50 = B * 4320000 / S - 1 / t_50 = 4320000 / S - t_50 = S / 4320000 -``` +- [Resource system contract reference implementation](https://github.com/koinos/koinos-contracts-cpp/blob/80f55538a5fbf6526e2e1df93d9bf4981eb6c2e7/contracts/resources/resources.cpp) +- [Resource schemas in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/tree/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/contracts/resources) +- [Chain resource system calls in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/chain/system_calls.proto) diff --git a/docs/architecture/serialization.md b/docs/architecture/serialization.md index 8d30526f..fdc640d8 100644 --- a/docs/architecture/serialization.md +++ b/docs/architecture/serialization.md @@ -3,28 +3,70 @@ icon: fontawesome/solid/cubes --- # Serialization -Koinos utilizes [Protocol Buffers](https://protobuf.dev/) for serializing data types between microservices and between the Koinos Blockchain Framework and the KVM. Protocol Buffers was chosen for a variety of reasons. The primary being the number of officially supported languages and flexibility of the specification to represent all cases required by Koinos. ---- -## Koinos Proto -[Koinos Proto](https://github.com/koinos/koinos-proto) is very foundation of Koinos' multilingual support. Every microservice broadcast event and every RPC is defined as a Protobuf message. Every smart contract transmits data in and out of the KVM via Protobuf serialization. This repository defines all interactions between clients, servers, system smart contracts, and microservices. Protobuf is also used to serialize internal data to disk for those microservices that require state. +Koinos uses [Protocol Buffers](https://protobuf.dev/) to define structured data +and encode it as bytes. A shared schema lets services, clients, and smart +contracts agree on field numbers, types, and nested messages even when they are +implemented in different languages. -The repository is organizationed by microservices under the `koinos/` directory. There are a handful of special directories, below find a comprehensive list. +## Where protobuf is used -| Directory | Description | -| --------- | ----------- | -| [koinos/broadcast](https://github.com/koinos/koinos-proto/tree/master/koinos/broadcast) | Defines the serialization for all broadcast events within the Koinos cluster. | -| [koinos/contracts](https://github.com/koinos/koinos-proto/tree/master/koinos/contracts) | Defines the serialization for all system smart contracts. | -| [koinos/protocol](https://github.com/koinos/koinos-proto/tree/master/koinos/protocol) | Defines the serialization for all data types on the wire that may be used for signing. | -| [koinos/rpc](https://github.com/koinos/koinos-proto/tree/master/koinos/rpc) | Defines the serialization for all Remote Procedure Calls (RPC). | +The versioned [`koinos-proto`](https://github.com/koinos/koinos-proto/tree/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80) +repository defines the main data boundaries: ---- -## Canonicity -Protocol Buffers does not specifiy a deterministic serialization for each type. This is a feature of the protocol to increase flexibility. But when cryptographic integrity is required, this is a liability. Thankfully, the Protocol Buffers serialization is not difficult to understand and enforcing canonicity is relatively straight forward. Every field of a Protocol Buffers message must have an integer index. This is a natural sort order. Futhermore, maps are not guaranteeed to be serialized in any particular order. This appears to be due to the fact that not all targeted languages can guarantee a particular order. For example, Golang purposefully randomizes the iteration order of a map to prevent developers from relying on a particular ordering. Koinos Blockchain Framework has no need of maps, so this is not an issue for us. From these restraints the canonical serialization is as follows: +| Boundary | Examples | +| --- | --- | +| Protocol objects | Blocks, block headers, transactions, operations, and receipts | +| Service RPC | Chain queries, block lookup, pending transactions, and derived indexes | +| Broadcasts | Accepted blocks, irreversible blocks, transaction results, and contract events | +| Smart contract runtime | Contract arguments, results, system-call messages, and events | +| Contract ABI | Type descriptors used to encode a contract's arguments and results | + +Individual services may also serialize protobuf messages in their persistent +state. That storage format remains owned by the service and is not automatically +a public compatibility contract. + +## Schema and wire data + +A `.proto` file is the schema. Generated language bindings or runtime +descriptors encode and decode the wire data. The schema name alone is not +enough: a client and service must use compatible field definitions. + +Protocol Buffers supports compatible schema evolution when field numbers and +wire types are managed correctly. Renaming or reusing a field number can be +breaking even if the new source code still compiles. + +## Signed and hashed data + +Protocol Buffers does not promise that every implementation will produce an +identical byte sequence for every logically equivalent message. That matters +when bytes are hashed or signed. + +Koinos protocol objects define the representation expected by the protocol. +Applications should use an official Koinos SDK or a tested compatible +implementation when building transaction IDs, signatures, block IDs, or other +cryptographically referenced values. Re-encoding a message with an arbitrary +protobuf library can produce bytes that do not match the expected signed +payload. + +## Contract data + +The Chain service passes contract arguments and results across the WebAssembly +runtime boundary as byte arrays. The contract and caller use protobuf types to +interpret those bytes. A [Contract ABI](contract-abi.md) connects a method's +entry point to its argument and result message types. + +Serialization errors are therefore interface errors: the contract may receive +the wrong field values or reject the call even though the byte array itself is +valid. -- Serialize fields in field number order -- Do not allow maps +For language-specific generation and contract examples, continue with +[Smart Contract Development](../contracts/protobuffers.md). -All messages that are cryptographically referenced or verified will be serialized using this serialization. The primary location where this will impact developers is transaction signing. +## Versioned sources -Learn more about how [Protobuf](../developers/protobuf.md) is used through the Koinos ecosystem. [Read more »](../developers/protobuf.md) \ No newline at end of file +- [`koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/tree/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80) +- [Protocol objects](https://github.com/koinos/koinos-proto/tree/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/protocol) +- [RPC schemas](https://github.com/koinos/koinos-proto/tree/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc) +- [Broadcast schemas](https://github.com/koinos/koinos-proto/tree/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/broadcast) +- [Chain runtime boundary](https://github.com/koinos/koinos-chain/tree/0ae99eced8b585c4145424e9c2a28f667796cc66) diff --git a/docs/architecture/smart-contracts.md b/docs/architecture/smart-contracts.md index 0caea00a..da8c6eee 100644 --- a/docs/architecture/smart-contracts.md +++ b/docs/architecture/smart-contracts.md @@ -3,153 +3,96 @@ icon: fontawesome/solid/code --- # Smart contracts -The Koinos Blockchain Framework is a bare bones minimal blockchain implementation that is fully customizable through the use of smart contracts. Smart contracts can implement both feature rich -decentralized applications and core system functionality. The information in this documented is intended to be SDK agnostic and explain the core functionality of the Koinos Virtual Machine and its -implementation. -Because Koinos uses [Fizzy](https://github.com/wasmx/fizzy) for its WASM (WebAssembly) virtual machine, the blockchain is agnostic to the language the smart contract has been written -- this allows -support for a multitude of programming languages for development. +Koinos smart contracts are WebAssembly modules executed by Chain. Contracts +implement application behavior, and selected system contracts also implement +protocol behavior that would otherwise require a native node upgrade. -Smart contracts come in two flavors: user and system. User contracts have a basic set of features that allow the developer to -write decentralized applications. System contracts have all the features available to user contracts, with the additional ability of access the system contract space. +The node remains responsible for validation, execution context, resource +metering, state commits, receipts, and consensus. Contract code cannot bypass +those boundaries. -## Contract space -Each smart contract has access to an `object_space`, which essentially defines a key value store. The `object_space` is defined as follows: +## Execution boundary -```proto -message object_space { - bool system = 1; - bytes zone = 2; - uint32 id = 3; -} -``` - -### User space -In the case of a user contract `system` will be set to `false`, the `zone` will be set to the bytes of the public address of the contract, and `id` is used as a unique identifier distinguishing between multiple key value stores. A contract may -have different key value stores by incrementing the `id`. - -### System space -The system contract is special in that it may access a _global_ space denoted by `system` being `true` and the `zone` being set to an empty byte array, otherwise known as `kernel` space. This allows for system contracts to read and manipulate a pool -of shared key value stores. +A contract call identifies: ---- -## Entry points -To inform the blockchain which function you are calling within a smart contract an entry point is provided. The Koinos Blockchain Framework will take the request, whether it is a read or write, load up the contract and pass the entry point as a parameter. -The main function will then instantiate the contract class or execute procedurally and execute the corresponding code whether it is a member function or inline code. Entry points come in two flavors: read and write. - -### Read-only entry points -Read-only entry points are often used to implement "getter" functions and can be called outside of a transaction. Most commonly, the read only entry points are called using the RPC method `read_contract`. Smart contract code that is executed -in read-only mode is prevented from writing to any key value store. If the contract attempts to perform a write during read-only mode it will be abruptly trapped and a permission denied exception will be thrown. - -Given the following RPC request and response definitions: - -```proto -message read_contract_request { - bytes contract_id = 1 [(btype) = CONTRACT_ID]; - uint32 entry_point = 2; - bytes args = 3; -} -``` +- a contract ID; +- a 32-bit entry point; and +- protobuf-encoded argument bytes. -```proto -message read_contract_response { - bytes result = 1; - repeated string logs = 2; -} -``` +Chain loads the contract, creates an execution context, invokes the entry point, +meters the work, and returns protobuf-encoded result bytes. The +[Contract ABI](contract-abi.md) lets tools map human-readable method names to +entry points and message types. ```mermaid - - sequenceDiagram - Client->>+RPC microservice: read_contract_request - RPC microservice->>+Koinos Chain: read_contract_request - Koinos Chain->>+Koinos Virtual Machine: contract execution - Koinos Virtual Machine->>-Koinos Chain: contract execution - Koinos Chain->>-RPC microservice: read_contract_response - RPC microservice->>-Client: read_contract_response +sequenceDiagram + participant Client + participant API as API gateway + participant Chain + participant KVM as WebAssembly runtime + + Client->>API: Contract request + API->>Chain: Protobuf RPC + Chain->>KVM: Contract ID, entry point, arguments + KVM-->>Chain: Result, state changes, logs, events + Chain-->>API: Receipt or read result + API-->>Client: External API response ``` -_**Figure 1.** A diagram demonstrating the data path of a `read_contract_request` from an RPC client._ - -### Writable entry points -Writable entry points have no restrictions with regards to reading or writing data. If the smart contract code attempts to write to a key value store, it must be executed in writable mode. This is accomplished by calling the contract from within -a transaction. +## Read-only calls and transactions -Using the `call_contract_operation` defined below, a user may submit a transaction containing the operation which in turn calls the smart contract in a writable mode. - -```proto -message call_contract_operation { - bytes contract_id = 1 [(btype) = CONTRACT_ID]; - uint32 entry_point = 2; - bytes args = 3; -} -``` +A `read_contract` RPC executes a contract against node state without committing +state changes. It is suitable for queries, but its result reflects the Chain +state reached by that node. -Given the following RPC request and response definitions: +A writable contract call is an operation inside a signed transaction. Chain +checks authorization, nonce, resource availability, and contract execution +before committing the resulting state. If execution fails, the state changes +from that transaction are not committed. -```proto -message submit_transaction_request { - protocol.transaction transaction = 1; - bool broadcast = 2; -} -``` +The API path does not change these rules. JSON-RPC, gRPC, and REST only +translate or route the request. -```proto -message submit_transaction_response { - protocol.transaction_receipt receipt = 1; -} -``` +## Contract state -```mermaid +Contract objects are stored in named object spaces. A user contract's storage +is separated by its contract identifier and object-space ID. System contracts +can receive authority to work with system state and replace selected +[system calls](system-calls.md). - sequenceDiagram - Client->>+RPC microservice: submit_transaction_request - RPC microservice->>+Koinos Chain: submit_transaction_request - Koinos Chain->>+Koinos Virtual Machine: contract execution - Koinos Virtual Machine->>-Koinos Chain: contract execution - Koinos Chain->>-RPC microservice: submit_transaction_response - RPC microservice->>-Client: submit_transaction_response -``` +State becomes part of the selected chain only when the containing transaction +and block are accepted. Recent accepted state can still change after a fork +until it becomes irreversible. -_**Figure 2.** A diagram demonstrating the data path of a `submit_transaction_request` from an RPC client._ +## Calls, logs, and events ---- -## Contract buffers +A contract can call another contract through the `call` system call. Chain +creates a nested execution frame, preserves caller context, and returns the +callee's encoded result. -Because Koinos passes data between the system and contracts using a serialized protocol buffer format, a buffer is used in the interchange of data. There is a cost in CPU cycles when allocating -data within the VM and therefore it costs mana. It is recommended you set your contract buffer to the lowest size possible that will fit both your contract inputs and contract outputs in order to -maintain efficiency with regards to resource usage. +Contracts can emit: ---- -## Intercontract communication -Smart contracts do not necessarily operate in a silo. Any contract has to capability to call upon another contract. This is achieve through a system call, `call`. Similar to both `read_contract` and -`contract_call_operation` it takes similar paremeters and is defined as: - -```proto -message call_arguments { - bytes contract_id = 1 [(btype) = CONTRACT_ID]; - uint32 entry_point = 2; - bytes args = 3; -} -``` +- **logs**, intended primarily for execution diagnostics; and +- **events**, structured protobuf data recorded in receipts and distributed to + interested services. -With the corresponding response: +The caller and callee must agree on the protobuf types used for arguments, +results, and events. -```proto -message call_result { - bytes value = 1; -} -``` +## User and system contracts -It is up to the developer to serialize the contract input and output data correctly to ensure the integrity of the call between contracts. +User contracts build applications within the normal runtime permissions. System +contracts have explicitly assigned protocol responsibilities and can override +selected system-call behavior. -```mermaid +This page explains the runtime boundary. Privileged contracts and governance +controls belong in [System Contracts](../system-contracts/index.md), while build +and deployment procedures belong in +[Smart Contract Development](../contracts/index.md). - sequenceDiagram - Smart contract 1->>+Koinos Chain: call_arguments - Koinos Chain->>+Smart contract 2: call_arguments - Smart contract 2->>-Koinos Chain: call_result - Koinos Chain->>-Smart contract 1: call_result -``` +## Versioned sources -_**Figure 3.** A diagram demonstrating the data path of a smart contract calling another smart contract._ \ No newline at end of file +- [`koinos-chain` v1.5.2](https://github.com/koinos/koinos-chain/tree/0ae99eced8b585c4145424e9c2a28f667796cc66) +- [Contract operations in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/protocol/protocol.proto) +- [System-call schemas in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/chain/system_calls.proto) diff --git a/docs/architecture/system-calls.md b/docs/architecture/system-calls.md index 110dcd89..7819c967 100644 --- a/docs/architecture/system-calls.md +++ b/docs/architecture/system-calls.md @@ -3,143 +3,70 @@ icon: fontawesome/solid/left-right --- # System calls -System calls are how requests to the Koinos Blockchain Framework are made. Each system call provides important functionality to be utilized from smart contracts or other parts of the framework. - -Each system call has its base functionality implemented natively in a function known as a "thunk". What differentiates a system call from its thunk, is that the system call can have its functionality overridden by a special type of smart contract known as a "system contract". - -|System Call|Description| -|---|---| -|`get_head_info`|Retrieves the current head block information| -|`apply_block`|Applies a block to the blockchain| -|`apply_transaction`|Applies a transaction to the current block| -|`apply_upload_contract_operation`|Applies an upload contract operation to the current transaction| -|`apply_call_contract_operation`|Applies a call contract operation to the current transaction| -|`apply_set_system_call_operation`|Applies a set system call operation to the current transaction| -|`apply_set_system_contract_operation`|Applies a set system contract operation to the current transaction| -|`pre_block_callback`|Callback prior to block application| -|`post_block_callback`|Callback after block application| -|`pre_transaction_callback`|Callback prior to transaction application| -|`post_transaction_callback`|Callback after transaction application| -|`get_chain_id`|Retrieves the current chain ID| -|`process_block_signature`|Handles block signatures during block application| -|`get_transaction`|Retrieves the current transaction| -|`get_transaction_field`|Retrieves a field from the current transaction| -|`get_block`|Retrieves the current block| -|`get_block_field`|Retrieves a field from the current block| -|`get_last_irreversible_block`|Retrieves the last irreversible block height| -|`get_account_nonce`|Retrieves the last account nonce| -|`verify_account_nonce`|Verifies the account nonce| -|`set_account_nonce`|Sets an account nonce| -|`check_system_authority`|Verifies whether the system authorizes the action| -|`get_operation`|Retrieves the current operation| -|`get_account_rc`|Retrieves the current account resource credits| -|`consume_account_rc`|Consumes resource credits on an account| -|`get_resource_limits`|Retrieves the current resource limits| -|`consume_block_resources`|Consumes resource credits for the block| -|`put_object`|Inserts data into a key value store| -|`remove_object`|Deletes data in the key value store| -|`get_object`|Retrieves data from the key value store| -|`get_next_object`|Iterates forward through the key value store| -|`get_prev_object`|Iterates backwards through the key value store| -|`log`|Emits a log entry| -|`event`|Emits an event| -|`hash`|Performs a hashing algorithm on given data| -|`recover_public_key`|Recovers a public key| -|`verify_merkle_root`|Validates a merkle root given leaves| -|`verify_signature`|Validates a signature| -|`verify_vrf_proof`|Validate a verifiably random proof| -|`call`|Calls another smart contract| -|`exit`|Stops smart contract execution| -|`get_arguments`|Retrieves arguments passed to a smart contract| -|`get_contract_id`|Retrieves the current smart contract ID| -|`get_caller`|Retrieves the caller of the smart contract| -|`check_authority`|Validates authorization was given| -|`get_contract_name`|Retrieves the name of a smart contract given the address from the name service| -|`get_contract_address`|Retrieves the address of a smart contract given the name from the name service| -|`get_contract_meta_data`|Retrieves meta information about a smart contract given the address| - -_**Table 1.** A comprehensive list of system calls._ - -Detailed information regarding the arguments and return values of system calls are defined as protocol buffer messages in the [Koinos Proto](https://github.com/koinos/koinos-proto/blob/master/koinos/chain/system_calls.proto) repository. - -## Overriding system calls -While any system call can be overridden by a contract that simply calls the underlying thunk, the underlying functionality of some of them cannot be reproduced in the KVM. **Table 2** lists system calls which cannot be fully replaced by an override, and the reason it cannot be overridden. - -_**Table 2.** System calls which cannot be overridden_ - -|System Call|Reason| -|---|---| -|`apply_block`|Requires access to the execution context| -|`apply_set_system_call_operation`|Requires call to `get_transaction`| -|`apply_set_system_contract_operation`|Requires call to `get_transaction`| -|`apply_transaction`|Requires state access| -|`call`|Requires stack frame access| -|`event`|Requires event recorder access| -|`exit`|Would cause infinite recursion| -|`get_caller`|Requires stack frame access and caller access on execution environment| -|`get_arguments`|Requires access to contract call arguments on execution environment| -|`get_contract_id`|Requires access to contract id on execution environment| -|`get_head_info`|Requires state access| -|`get_last_irreversible_block`|Requires state access| -|`get_next_object`|Requires state access| -|`get_object`|Requires state access| -|`get_prev_object`|Requires state access| -|`put_object`|Requires state access| ---- -## Thunks -Ultimately system calls you make ends up manipulating native code. The native functions that get invoked are known as thunks. When the Koinos blockchain launched all system calls were a light translation layer that directly mapped to thunks implemented in C++. While system calls can be implemented via smart contract or native code, thunks only exist as native C++ implementations. - -There are several reasons for implementing functionality via thunks. Some system calls require low level access and can only be implemented natively. As part of the Koinos Blockchain Framework design, we attempt to minimize these cases in order to facilitate forkless upgrades. Another reason to implement functionality via thunks is performance. It will always be more efficient to execute code natively than to run bytecode in the Koinos Virtual Machine. This results in lower the mana costs which improves the user experience. - -System contracts have unique abilities when compared to user contracts. Aside from accessing kernel space, system contracts can call thunks directly. This makes it possible to alter the behavior of a system call that requires calling a thunk with pre and post processing in the KVM. - -|Thunk|Description| -|---|---| -|`get_head_info`|Retrieves the current head block information| -|`apply_block`|Applies a block to the blockchain| -|`apply_transaction`|Applies a transaction to the current block| -|`apply_upload_contract_operation`|Applies an upload contract operation to the current transaction| -|`apply_call_contract_operation`|Applies a call contract operation to the current transaction| -|`apply_set_system_call_operation`|Applies a set system call operation to the current transaction| -|`apply_set_system_contract_operation`|Applies a set system contract operation to the current transaction| -|`pre_block_callback`|Callback prior to block application| -|`post_block_callback`|Callback after block application| -|`pre_transaction_callback`|Callback prior to transaction application| -|`post_transaction_callback`|Callback after transaction application| -|`get_chain_id`|Retrieves the current chain ID| -|`process_block_signature`|Handles block signatures during block application| -|`get_transaction`|Retrieves the current transaction| -|`get_transaction_field`|Retrieves a field from the current transaction| -|`get_block`|Retrieves the current block| -|`get_block_field`|Retrieves a field from the current block| -|`get_last_irreversible_block`|Retrieves the last irreversible block height| -|`get_account_nonce`|Retrieves the last account nonce| -|`verify_account_nonce`|Verifies the account nonce| -|`set_account_nonce`|Sets an account nonce| -|`check_system_authority`|Verifies whether the system authorizes the action| -|`get_operation`|Retrieves the current operation| -|`get_account_rc`|Retrieves the current account resource credits| -|`consume_account_rc`|Consumes resource credits on an account| -|`get_resource_limits`|Retrieves the current resource limits| -|`consume_block_resources`|Consumes resource credits for the block| -|`put_object`|Inserts data into a key value store| -|`remove_object`|Deletes data in the key value store| -|`get_object`|Retrieves data from the key value store| -|`get_next_object`|Iterates forward through the key value store| -|`get_prev_object`|Iterates backwards through the key value store| -|`log`|Emits a log entry| -|`event`|Emits an event| -|`hash`|Performs a hashing algorithm on given data| -|`recover_public_key`|Recovers a public key| -|`verify_merkle_root`|Validates a merkle root given leaves| -|`verify_signature`|Validates a signature| -|`verify_vrf_proof`|Validate a verifiably random proof| -|`call`|Calls another smart contract| -|`exit`|Stops smart contract execution| -|`get_arguments`|Retrieves arguments passed to a smart contract| -|`get_contract_id`|Retrieves the current smart contract ID| -|`get_caller`|Retrieves the caller of the smart contract| -|`check_authority`|Validates authorization was given| - -_**Table 3.** A comprehensive list of thunks._ \ No newline at end of file +System calls are the controlled interface between WebAssembly contracts and the +capabilities provided by Chain. A contract uses them to read or write state, +inspect its execution context, call another contract, emit an event, use +cryptographic functions, or consume blockchain resources. + +An ordinary contract call invokes another contract's entry point. A system call +crosses from the contract runtime into a capability managed by the blockchain +framework. + +## System calls and thunks + +Each system call has a native implementation called a **thunk**. Chain dispatches +the call to that implementation unless the active protocol configuration +assigns an authorized system contract as the override. + +```mermaid +flowchart TB + Contract["WebAssembly contract"] --> Call["System-call interface"] + Call --> Override{"Override active?"} + Override -- "No" --> Thunk["Native thunk"] + Override -- "Yes" --> SystemContract["Authorized system contract"] + SystemContract --> Thunk +``` + +This design leaves low-level capabilities in the node while allowing selected +protocol behavior to change through governed contract upgrades. A system +contract can call a thunk directly when it needs the native primitive as part +of its implementation. + +## Capability groups + +The versioned schema defines system calls in several groups: + +| Group | Examples | +| --- | --- | +| Execution context | Current block, transaction, operation, caller, and contract ID | +| State | Read, write, remove, and iterate objects | +| Contract execution | Read arguments, call another contract, and exit | +| Authorization | Check account or system authority and verify nonces | +| Resources | Read account Resource Credits and consume transaction or block resources | +| Cryptography | Hashing, signature verification, public-key recovery, Merkle proofs, and VRF verification | +| Observability | Contract logs and structured events | +| Protocol hooks | Block, transaction, and operation processing callbacks | + +The complete list is tied to the selected `koinos-proto` and Chain releases. +Applications should not copy a static list into their own compatibility logic. + +## Consensus and security boundary + +System calls run inside deterministic block execution. Their results, state +changes, resource use, logs, and events contribute to the transaction receipt +and the state selected by consensus. + +Changing a system-call override changes protocol behavior. Only operations with +the required system authority can make that assignment. The governance and +privileged-contract model is documented under +[System Contracts](../system-contracts/index.md). + +Contract developers normally use their SDK's typed system-call wrappers rather +than constructing the low-level protobuf messages directly. + +## Versioned sources + +- [System-call schemas in `koinos-proto` v2.6.0](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/chain/system_calls.proto) +- [Chain thunk documentation at v1.5.2](https://github.com/koinos/koinos-chain/blob/0ae99eced8b585c4145424e9c2a28f667796cc66/docs/thunks.md) +- [Chain system-call implementation at v1.5.2](https://github.com/koinos/koinos-chain/tree/0ae99eced8b585c4145424e9c2a28f667796cc66/src/koinos/chain) diff --git a/drafts/architecture/ARCHITECTURE_DOCUMENTATION_PLAN.md b/drafts/architecture/ARCHITECTURE_DOCUMENTATION_PLAN.md new file mode 100644 index 00000000..2c4cc0d3 --- /dev/null +++ b/drafts/architecture/ARCHITECTURE_DOCUMENTATION_PLAN.md @@ -0,0 +1,187 @@ +# Architecture Documentation Plan + +> [!IMPORTANT] +> **Internal planning document — not published.** This file and the material under +> `drafts/architecture/` are outside the MkDocs `docs_dir`. They are inputs for +> future documentation work, not approved user-facing documentation. + +## Objective + +Create a technically accurate, maintainable Architecture chapter for Koinos +without carrying forward stale operational guidance or exposing unfinished +material to readers. + +The first input to that work is the +[internal microservices foundation](microservices/README.md). It recovers useful +structural knowledge from the historical Koinos One documentation and reconciles +it with versioned current Koinos sources. It is deliberately not part of the +published site. + +## Boundaries for the current phase + +- Keep `drafts/architecture/` as internal technical source material; adapt it + for readers instead of publishing it directly. +- Public Architecture changes may update `mkdocs.yml` and `docs/architecture/` + after a claim has been verified against the selected source baseline. +- Do not present the internal drafts as complete or authoritative user + documentation. +- Do not copy the historical Koinos One pages wholesale. +- Do not import Knodel- or Windows-specific instructions, GarageMQ details, + stale image versions, seed addresses, ports, storage estimates, recovery + procedures, or unverified performance claims. +- Keep node operation, configuration, ports, backup and restore, publishing, + and deployment workflows in the Node Operators chapter. +- Keep implementation details for privileged system contracts in the System + Contracts chapter, linking from Architecture only when architectural context + is necessary. +- Use stable, versioned official sources for every technical claim promoted to + public documentation. + +## Phase 1 — Build the internal source foundation + +Status: **completed in `drafts/architecture/microservices/`** + +1. Record the source boundaries and pinned revisions in the + [microservices draft index](microservices/README.md). +2. Establish a current system-level model in + [Microservices overview](microservices/overview.md). +3. Explain RabbitMQ, protobuf RPC, and broadcast relationships in + [Internal messaging](microservices/internal-messaging.md). +4. Draft one technical record for every current service: + + - Chain + - Block Store + - P2P + - Mempool + - Transaction Store + - Block Producer + - JSON-RPC + - gRPC + - REST + - Contract Meta Store + - Account History + +5. Use the same structure for each service: purpose; dependencies and inputs; + outputs, RPCs, and broadcasts; persistent state; failure and consistency + considerations; publication verification; and versioned sources. +6. Mark uncertainties explicitly instead of filling gaps with assumptions. + +Deliverable: a reviewable internal technical baseline, still outside the +published site. + +## Phase 2 — Verify against current official Koinos + +Status: **completed for the current documentation baseline** + +Before editorial work, select the Koinos release or commit that the next +documentation update will describe. Then: + +1. Recheck the Compose service set, profiles, and dependency graph at that exact + revision. +2. Recheck RPC methods, message envelopes, and broadcasts against the matching + `koinos-proto` revision. +3. Review each service repository at a compatible tag or commit for: + + - state ownership and storage engine; + - startup and catch-up dependencies; + - inputs and outputs; + - fork and irreversible-block handling; + - failure behavior and rebuildability; + - public-interface versus internal-interface responsibilities. + +4. Resolve every item under each draft's “Verification before publication” + section. +5. Record source links using immutable tags or full commit hashes. +6. Ask the relevant Koinos maintainers to review areas where code alone does not + establish the intended architecture. + +Deliverable: a technically verified foundation tied to one coherent Koinos +revision. + +The selected deployment baseline is the official `koinos` bundle at commit +`821674672e699bf56e94d7c0e8bce122e83d1482`, including the service tags in its +`env.example`. RPC and broadcast descriptions use `koinos-proto` v2.6.0 and +were checked against the descriptor shipped by the bundle. Public pages avoid +claims that are not established by this baseline. + +## Phase 3 — Design the future reader journey + +Status: **completed for the current Architecture update** + +Define the audience and information architecture before modifying public pages. +The likely Architecture structure is: + +1. **Architecture overview** — system boundaries, the microservice model, data + flow, and the distinction between internal messaging and peer-to-peer + networking. +2. **Microservices** — a readable overview plus focused service pages, derived + from the verified internal foundation. +3. **Consensus and Proof of Burn** — architectural behavior only; operational + production setup remains in Node Operators. +4. **Smart contracts, ABI, system calls, and serialization** — runtime + boundaries and data contracts, without duplicating SDK tutorials. +5. **Resources** — architectural resource accounting and relevant links. + +During this phase: + +- identify beginner, application-developer, contract-developer, and operator + needs; +- decide which service details belong on individual pages and which belong in + diagrams or reference tables; +- remove empty or redundant navigation destinations; +- separate durable concepts from release-specific implementation notes; +- replace stale or invented terminology with established Koinos terms; +- link to Node Operators and System Contracts instead of duplicating their + procedures. + +Deliverable: an approved public outline and editorial brief. No public content +is promoted merely because the internal drafts exist. + +## Phase 4 — Promotion into published documentation + +Status: **in progress; implementation completed and validation pending** + +Only after technical and editorial review: + +1. Update the Architecture landing page and navigation. +2. Replace or remove empty microservice placeholders. +3. Adapt verified material from the drafts for the intended audience; do not + simply move files from `drafts/` to `docs/`. +4. Update the overview, Microservices, Proof of Burn, ABI, system calls, + Resources, Smart Contracts, and Serialization pages as required by the + approved outline. +5. Add diagrams only where they make service boundaries or data flow easier to + understand. +6. Add versioned official references close to the claims they support. +7. Keep operational commands and procedures in Node Operators. + +Promotion checks: + +- no unresolved verification markers; +- no empty public navigation targets; +- no stale network, version, port, or deployment claims; +- no duplicated operator or system-contract procedures; +- terminology matches current official Koinos repositories; +- maintainers have reviewed safety- or consensus-sensitive explanations. + +## Validation for future published changes + +Run the repository's normal validation plus focused Architecture checks: + +- validate all local and external links; +- build MkDocs with strict warnings where supported; +- inspect navigation and previous/next relationships; +- review every changed page at desktop and mobile widths; +- check tables, diagrams, code overflow, anchor links, and browser console + errors; +- confirm versioned source links resolve to the intended revision; +- run `git diff --check`; +- confirm that only intended files are tracked. + +## Current completion condition + +The present phase is complete when the internal foundation remains outside the +generated site, the public Architecture reader journey contains no empty +destinations, every published technical claim is supported by the selected +versioned sources, repository link and MkDocs checks pass without new warnings, +and desktop and mobile review finds no navigation, layout, or console problem. diff --git a/drafts/architecture/microservices/README.md b/drafts/architecture/microservices/README.md new file mode 100644 index 00000000..983bdd21 --- /dev/null +++ b/drafts/architecture/microservices/README.md @@ -0,0 +1,102 @@ +# Koinos Microservices Architecture — Internal Foundation + +> [!IMPORTANT] +> **Internal draft — not published.** These files are technical source material +> for a later Architecture rewrite. They require editorial and maintainer review +> before any content is adapted into `docs/`. + +## Purpose + +This directory reconstructs a maintainable technical baseline for the original +Koinos microservice architecture. It combines: + +- useful structural explanations from the historical Koinos One documents; +- the service topology in a pinned official Koinos Compose revision; +- current service behavior from official service repositories; and +- RPC and broadcast definitions from a pinned `koinos-proto` revision. + +The drafts describe architecture, not node operation. They intentionally omit +commands, ports, deployment configuration, key handling, backups, restoration, +and production procedures. + +## Draft set + +- [Microservices overview](overview.md) +- [Internal messaging](internal-messaging.md) +- [Chain](services/chain.md) +- [Block Store](services/block-store.md) +- [P2P](services/p2p.md) +- [Mempool](services/mempool.md) +- [Transaction Store](services/transaction-store.md) +- [Block Producer](services/block-producer.md) +- [JSON-RPC](services/json-rpc.md) +- [gRPC](services/grpc.md) +- [REST](services/rest.md) +- [Contract Meta Store](services/contract-meta-store.md) +- [Account History](services/account-history.md) + +## Common draft template + +Every service record uses these sections: + +1. Purpose +2. Dependencies and inputs +3. Outputs, RPCs, and broadcasts +4. Persistent state +5. Failure and consistency considerations +6. Verification before publication +7. Versioned sources + +The “Verification before publication” section is part of the content, not a +formality. It records claims that still need source, compatibility, or +maintainer confirmation before promotion. + +## Source policy + +The historical source is +[`koinos-one` commit `e031c91c1525de7683794fcb91d28edeb414a08b`](https://github.com/koinos/koinos-one/tree/e031c91c1525de7683794fcb91d28edeb414a08b/docs/microservices). +It documents AMQP Broker, Block Producer, Block Store, Chain, Contract Meta +Store, JSON-RPC, Mempool, and P2P. It does not document gRPC, Transaction Store, +Account History, or REST. + +That material is used only to identify durable concepts and useful explanatory +structure. It is not authoritative for current versions, deployment, topology, +configuration, performance, storage, networking, or operations. + +Current facts in this foundation were inspected at these official revisions: + +| Repository | Pinned revision | Role in this foundation | +| --- | --- | --- | +| [`koinos/koinos`](https://github.com/koinos/koinos/tree/821674672e699bf56e94d7c0e8bce122e83d1482) | `821674672e699bf56e94d7c0e8bce122e83d1482` | Compose topology and profiles | +| [`koinos/koinos-proto`](https://github.com/koinos/koinos-proto/tree/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80) | `f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80` (`v2.6.0`) | RPC and broadcast contracts | +| [`koinos/koinos-chain`](https://github.com/koinos/koinos-chain/tree/0ae99eced8b585c4145424e9c2a28f667796cc66) | `0ae99eced8b585c4145424e9c2a28f667796cc66` | Chain behavior | +| [`koinos/koinos-block-store`](https://github.com/koinos/koinos-block-store/tree/2bb94558df61c71eb241002635444cdddce0843c) | `2bb94558df61c71eb241002635444cdddce0843c` | Block storage | +| [`koinos/koinos-p2p`](https://github.com/koinos/koinos-p2p/tree/e2267ba230960b5e4100c16ad84c42cfc12eec4b) | `e2267ba230960b5e4100c16ad84c42cfc12eec4b` | Peer networking and synchronization | +| [`koinos/koinos-mempool`](https://github.com/koinos/koinos-mempool/tree/3f2a276e4b3e4fa37c69031b2f6f707915644086) | `3f2a276e4b3e4fa37c69031b2f6f707915644086` | Pending transactions | +| [`koinos/koinos-transaction-store`](https://github.com/koinos/koinos-transaction-store/tree/c8d985ab1b0dd3862fd2d0099f4458ebc6e0920c) | `c8d985ab1b0dd3862fd2d0099f4458ebc6e0920c` | Transaction index | +| [`koinos/koinos-block-producer`](https://github.com/koinos/koinos-block-producer/tree/8896d7aabbe9e0d154a5f7860920e95d17fd8cb4) | `8896d7aabbe9e0d154a5f7860920e95d17fd8cb4` | Block assembly and production | +| [`koinos/koinos-jsonrpc`](https://github.com/koinos/koinos-jsonrpc/tree/2c9433c67f2f60c920525a6c4bd3e15b0b51d94a) | `2c9433c67f2f60c920525a6c4bd3e15b0b51d94a` | JSON-RPC gateway | +| [`koinos/koinos-grpc`](https://github.com/koinos/koinos-grpc/tree/3a94c34fa002552ef586cd1af9bfd34d175430d3) | `3a94c34fa002552ef586cd1af9bfd34d175430d3` | gRPC gateway | +| [`koinos/koinos-rest`](https://github.com/koinos/koinos-rest/tree/d7f5bc90f11f78af9167e64913a028c00036d134) | `d7f5bc90f11f78af9167e64913a028c00036d134` | REST and OpenAPI gateway | +| [`koinos/koinos-contract-meta-store`](https://github.com/koinos/koinos-contract-meta-store/tree/64e803e1db1a9bb2946ae379ddad0e5611442ec5) | `64e803e1db1a9bb2946ae379ddad0e5611442ec5` | Contract metadata index | +| [`koinos/koinos-account-history`](https://github.com/koinos/koinos-account-history/tree/1d592c40ddd06c022eab3153266bd428752c6ded) | `1d592c40ddd06c022eab3153266bd428752c6ded` | Account history index | + +These service revisions are the tags selected together by the official +`koinos` bundle's versioned `env.example`. The protobuf descriptions use +`koinos-proto` v2.6.0 and were cross-checked against the descriptor shipped by +that bundle. The [Architecture plan](../ARCHITECTURE_DOCUMENTATION_PLAN.md) +records the verification and publication phases. + +## Excluded material + +Do not add the following to this foundation: + +- Knodel- or Windows-specific setup; +- GarageMQ implementation details; +- image tags, seed addresses, ports, or environment-variable inventories; +- hardware, storage, or performance estimates without current measurements; +- backup, restore, reindex, resync, or recovery procedures; +- block-producer key handling or irreversible transaction examples; +- operator helper scripts or documentation-owned tooling. + +Those topics either belong in Node Operators or need their own verified design. diff --git a/drafts/architecture/microservices/internal-messaging.md b/drafts/architecture/microservices/internal-messaging.md new file mode 100644 index 00000000..2ebc27b8 --- /dev/null +++ b/drafts/architecture/microservices/internal-messaging.md @@ -0,0 +1,109 @@ +# Internal Messaging + +> [!IMPORTANT] +> **Internal draft — not published.** Exchange names and message relationships +> were checked at pinned revisions and must be revalidated before publication. + +## Purpose + +Koinos microservices communicate through RabbitMQ using protobuf messages. This +internal messaging layer lets a service call another service without embedding +it in the same process and lets one event be observed by multiple interested +services. + +RabbitMQ is an internal coordination component. It is not the peer-to-peer +network, and it should not be described as the transport between independent +Koinos nodes. + +## Two communication patterns + +### RPC + +An RPC has a request, one target service, and a response. The protobuf RPC +definitions identify the service and method contracts. Gateways such as +JSON-RPC and gRPC translate external requests into these internal calls. + +At the inspected revisions, service RPC messages use the `koinos.rpc` exchange +family. + +### Broadcasts + +A broadcast announces a state change or observation to any subscribed service. +Examples include accepted blocks, irreversible blocks, accepted or failed +transactions, fork heads, gossip status, and contract events. + +At the inspected revisions, broadcast messages use the `koinos.event` exchange +family. Broadcast consumers remain responsible for ordering, idempotency, +catch-up, and fork behavior appropriate to their state. + +```mermaid +sequenceDiagram + participant Client as External client + participant Gateway as API gateway + participant MQ as RabbitMQ + participant Chain as Chain + participant Index as Derived index + + Client->>Gateway: External API request + Gateway->>MQ: Protobuf RPC request + MQ->>Chain: Route request + Chain-->>MQ: RPC response + MQ-->>Gateway: Route response + Gateway-->>Client: External protocol response + Chain->>MQ: Accepted-block broadcast + MQ-->>Index: Deliver broadcast + Note over Index: Validate ordering, fork handling, and catch-up +``` + +## Message contracts + +The pinned `koinos-proto` revision defines these broadcast message types: + +- `transaction_accepted` +- `transaction_failed` +- `mempool_accepted` +- `block_accepted` +- `block_irreversible` +- `fork_heads` +- `gossip_status` +- `event_parcel` + +The exact routing key, payload version, and consumer behavior must be read from +the matching service and protocol revisions. A message name alone does not +establish delivery guarantees or database consistency. + +## Failure and consistency considerations + +- If RabbitMQ is unavailable, local services may remain running while RPC and + broadcast coordination is interrupted. +- RPC timeouts do not establish whether the target completed work; callers need + method-specific retry semantics. +- Broadcast delivery and database commit are separate events. Consumers need + idempotent or otherwise safe processing. +- A slow indexer can expose data behind the Chain head. +- Fork changes can invalidate previously observed non-irreversible state. +- RabbitMQ durability and queue policy are deployment concerns and belong in + Node Operators, but Architecture must explain their consistency impact after + those policies are verified. +- Adding service replicas is not automatically safe. Stateful writers and + broadcast consumers need explicit ownership and coordination rules. + +## Verification before publication + +- Confirm the exchange and routing conventions against the release selected for + documentation. +- Map the RPC methods and broadcasts used by each service from compatible + revisions. +- Confirm queue durability, replay, redelivery, and ordering behavior with the + implementation and maintainers. +- Distinguish behavior guaranteed by protobuf contracts from behavior provided + by the current RabbitMQ client libraries. +- Decide whether contract event routing belongs here or in the Smart Contracts + architecture page. + +## Versioned sources + +- [`koinos-proto` RPC envelope](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/rpc.proto) +- [`koinos-proto` service definitions](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/services.proto) +- [`koinos-proto` broadcasts](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/broadcast/broadcast.proto) +- [`koinos/koinos` RabbitMQ service](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/drafts/architecture/microservices/overview.md b/drafts/architecture/microservices/overview.md new file mode 100644 index 00000000..c0226428 --- /dev/null +++ b/drafts/architecture/microservices/overview.md @@ -0,0 +1,129 @@ +# Microservices Overview + +> [!IMPORTANT] +> **Internal draft — not published.** This architecture model is based on pinned +> official revisions and must be revalidated against the release selected for +> future public documentation. + +## System model + +A Koinos node is composed of cooperating microservices. RabbitMQ carries +internal protobuf RPC messages and broadcasts between those services. P2P is a +separate boundary: it communicates with other Koinos nodes and hands received +blocks and transactions into the local service graph. + +The Chain service owns consensus validation and authoritative chain state. +Other stateful services keep either durable blockchain artifacts or derived +indexes. API gateways translate external protocols into internal service +requests; they do not make a response authoritative merely by exposing it. + +```mermaid +flowchart LR + Peers["Other Koinos nodes"] <--> P2P["P2P"] + Apps["Applications and tools"] --> APIs["JSON-RPC / gRPC / REST"] + Producer["Block Producer"] --> Bus["RabbitMQ internal messaging"] + P2P --> Bus + APIs --> Bus + Bus <--> Chain["Chain"] + Bus <--> Mempool["Mempool"] + Bus <--> BlockStore["Block Store"] + Bus <--> Indexes["Transaction Store / Contract Meta Store / Account History"] +``` + +The arrows show communication relationships, not process ownership or a +complete message-level sequence. + +## Service set at the inspected Compose revision + +The pinned +[`koinos/koinos` Compose file](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) +starts a core service set and exposes additional capabilities through Compose +profiles. + +| Service | Compose role | Primary responsibility | +| --- | --- | --- | +| RabbitMQ (`amqp`) | Core | Internal service messaging | +| Chain | Core | Consensus validation, execution, fork choice, and canonical state | +| Mempool | Core | Pending transaction and resource reservation state | +| Block Store | Core | Durable blocks and receipts | +| P2P | Core | Peer networking, gossip, and block synchronization | +| Block Producer | Optional profile | Assemble, sign, and submit blocks when production is enabled | +| JSON-RPC | API profile | JSON-RPC gateway to internal services | +| gRPC | API profile | Typed protobuf gRPC gateway | +| REST | API profile | REST/OpenAPI interface backed by JSON-RPC | +| Transaction Store | API profile | Transaction lookup index | +| Contract Meta Store | API profile | Contract metadata and ABI lookup index | +| Account History | API profile | Fork-aware account history index | + +This grouping describes that exact Compose revision. It must not be generalized +to all releases without verification. + +## Architectural dependency graph + +Compose startup dependencies at the inspected revision are: + +| Service | Declared service dependencies | +| --- | --- | +| Chain | RabbitMQ | +| Mempool | RabbitMQ, Chain | +| Block Store | RabbitMQ, Chain | +| P2P | RabbitMQ, Block Store, Chain | +| Block Producer | RabbitMQ, Mempool, Chain | +| JSON-RPC | RabbitMQ, Chain | +| gRPC | RabbitMQ, Chain | +| Transaction Store | RabbitMQ, Chain | +| Contract Meta Store | RabbitMQ, Chain | +| Account History | RabbitMQ, Chain, Block Store | +| REST | JSON-RPC | + +`depends_on` is a deployment relationship, not a complete architecture +contract. A service can also depend on messages or RPCs from components that +are not represented by a direct startup edge. + +## State ownership + +| State category | Owner or maintainer | Consistency role | +| --- | --- | --- | +| Canonical chain state | Chain | Consensus-critical and authoritative | +| Blocks and receipts | Block Store | Durable blockchain artifacts | +| Pending transactions | Mempool | Fork-aware, transient working state | +| Transaction lookup | Transaction Store | Derived and rebuildable index | +| Contract metadata and ABI | Contract Meta Store | Derived and rebuildable index | +| Account activity history | Account History | Derived, fork-aware index | +| API protocol state | JSON-RPC, gRPC, REST | Gateway-level only; not canonical blockchain state | + +“Derived and rebuildable” does not mean disposable during normal operation. +An index can be unavailable, incomplete, or stale while it catches up, and API +consumers must not confuse that condition with the Chain service's view. + +## Cross-cutting consistency rules + +- Chain validation and fork choice determine accepted canonical state. +- Services consuming accepted-block broadcasts can lag behind Chain and need + explicit catch-up and fork handling. +- Mempool state changes as transactions are accepted, rejected, included, or + invalidated by chain movement. +- P2P transports data across nodes but does not replace local consensus + validation. +- RabbitMQ availability affects coordination among local services. +- Optional API and index services must not become implicit consensus + dependencies. +- Stateful services cannot be scaled safely by assuming every instance can + write the same state independently; ownership and consistency behavior must + be verified per service. + +## Publication questions + +Before adapting this overview into public documentation: + +- select a coherent release and regenerate the service/profile table; +- confirm which services are considered core, optional, or legacy; +- verify restart, catch-up, and fork behavior with maintainers; +- decide how much failure behavior each target audience needs; +- create a reader-focused diagram that avoids implying unverified data paths. + +## Versioned sources + +- [`koinos/koinos` Compose topology](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) +- [`koinos-proto` RPC services](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/services.proto) +- [`koinos-proto` broadcast contracts](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/broadcast/broadcast.proto) diff --git a/drafts/architecture/microservices/services/account-history.md b/drafts/architecture/microservices/services/account-history.md new file mode 100644 index 00000000..44c531fb --- /dev/null +++ b/drafts/architecture/microservices/services/account-history.md @@ -0,0 +1,72 @@ +# Account History + +> [!IMPORTANT] +> **Internal draft — not published.** History semantics, fork handling, and +> completeness require release-level verification. + +## Purpose + +Account History builds a per-account activity index from blockchain data. It +supports historical queries that would be expensive or inappropriate for Chain +to maintain as part of consensus state. + +It is a derived, fork-aware view rather than the source of account balances, +nonces, or contract state. + +## Dependencies and inputs + +- RabbitMQ for internal RPC and block broadcasts. +- Chain and Block Store as declared Compose dependencies. +- Accepted-block broadcasts for new history entries. +- Irreversible-block broadcasts for finality-related index maintenance. +- Stored blocks and receipts needed for catch-up or event interpretation. + +Account History is absent from the historical Koinos One microservice +documents, so this draft relies on current official sources. + +## Outputs, RPCs, and broadcasts + +The pinned protocol revision defines `get_account_history`, including pagination +and ordering fields described by its request and response schemas. + +The inspected service is primarily a broadcast consumer and RPC provider. No +Account-History-owned architecture broadcast was identified. + +## Persistent state + +The inspected implementation uses Koinos state-database components backed by +RocksDB. It stores a derived index associated with account activity and chain +position. + +The index must track fork movement correctly and distinguish accepted history +from history made irreversible. + +## Failure and consistency considerations + +- Account History can be behind Chain while otherwise returning valid older + entries. +- Non-irreversible entries can change after a fork. +- Pagination across a changing head can produce inconsistent client views + unless the API provides or the client records a stable boundary. +- “No history” can mean no matching activity or an incomplete index unless + catch-up status is exposed separately. +- The index is not authoritative for current account state. + +## Verification before publication + +- Define which operations, events, and affected addresses create history + entries. +- Verify accepted-block, irreversible-block, fork rollback, and catch-up + behavior. +- Confirm pagination, ordering, deduplication, and stable-boundary semantics. +- Establish how index progress or incompleteness can be observed. +- Confirm what portions of the index can be rebuilt from Block Store. +- Coordinate account-state explanations with Chain and application API pages. + +## Versioned sources + +- [`koinos-account-history` inspected revision](https://github.com/koinos/koinos-account-history/tree/1d592c40ddd06c022eab3153266bd428752c6ded) +- [`koinos-account-history` service implementation](https://github.com/koinos/koinos-account-history/blob/1d592c40ddd06c022eab3153266bd428752c6ded/src/koinos_account_history.cpp) +- [`koinos-proto` Account History RPC definitions](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/account_history/account_history_rpc.proto) +- [`koinos-proto` accepted and irreversible block broadcasts](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/broadcast/broadcast.proto) +- [Pinned Compose service](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/drafts/architecture/microservices/services/block-producer.md b/drafts/architecture/microservices/services/block-producer.md new file mode 100644 index 00000000..26e29d09 --- /dev/null +++ b/drafts/architecture/microservices/services/block-producer.md @@ -0,0 +1,76 @@ +# Block Producer + +> [!IMPORTANT] +> **Internal draft — not published.** Block production is safety-sensitive. +> This page contains no key-management, registration, burn, or production +> procedure and must not be used as an operator guide. + +## Purpose + +Block Producer assembles candidate blocks from pending transactions, asks Chain +to validate the proposal, signs and submits blocks when production is enabled, +and schedules work based on the active consensus rules. + +It is an optional service in the inspected Compose topology. A standard Koinos +node can validate and relay the chain without producing blocks. + +## Dependencies and inputs + +- RabbitMQ for internal RPC and broadcasts. +- Chain for head state, proposal validation, and block submission. +- Mempool for pending transactions and block-related state changes. +- Gossip-status information used to avoid producing without an adequate network + view. +- Producer configuration and signing authority, which are operational and + security concerns outside this Architecture draft. + +## Outputs, RPCs, and broadcasts + +Block Producer: + +- requests pending transactions from Mempool; +- constructs a block candidate; +- uses Chain proposal and submission paths; +- signs a valid candidate when production conditions are satisfied; and +- submits the produced block for local validation and subsequent propagation. + +The service does not expose a general public query API in the pinned +`koinos-proto` service list. + +## Persistent state + +Block Producer does not own canonical chain history. Its most sensitive durable +input is producer signing material, but key storage, unlocking, backup, and +rotation belong exclusively in reviewed Node Operators documentation. + +Any additional scheduling or cached state in the selected release must be +verified before publication. + +## Failure and consistency considerations + +- Producing from a stale head can result in a block that is not selected by the + network. +- Mempool, Chain, network status, and local time assumptions must be mutually + compatible. +- A submitted proposal still requires normal Chain validation. +- Signing-key exposure is materially different from P2P identity exposure. +- Duplicate or concurrent producers using the same authority can create + operational and consensus risks. +- A healthy process does not establish that the account is eligible or that + produced blocks are being accepted. + +## Verification before publication + +- Confirm the current production scheduling and eligibility model. +- Map Mempool and gossip-status inputs to production stop conditions. +- Verify proposal, signing, submission, and retry sequencing. +- Confirm what state, if any, is persisted outside signing material. +- Obtain maintainer review for every consensus- or signing-sensitive claim. +- Link later to Node Operators for procedures; do not duplicate them here. + +## Versioned sources + +- [`koinos-block-producer` inspected revision](https://github.com/koinos/koinos-block-producer/tree/8896d7aabbe9e0d154a5f7860920e95d17fd8cb4) +- [`koinos-block-producer` service implementation](https://github.com/koinos/koinos-block-producer/blob/8896d7aabbe9e0d154a5f7860920e95d17fd8cb4/src/koinos_block_producer.cpp) +- [`koinos-proto` Chain proposal and submission methods](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/chain/chain_rpc.proto) +- [Pinned Compose profile](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/drafts/architecture/microservices/services/block-store.md b/drafts/architecture/microservices/services/block-store.md new file mode 100644 index 00000000..6eef2f1c --- /dev/null +++ b/drafts/architecture/microservices/services/block-store.md @@ -0,0 +1,67 @@ +# Block Store + +> [!IMPORTANT] +> **Internal draft — not published.** Storage and catch-up behavior must be +> rechecked against the release selected for public documentation. + +## Purpose + +Block Store keeps durable blocks and receipts and serves historical block +lookups. It separates blockchain-artifact storage from the Chain service's +consensus state. + +## Dependencies and inputs + +- RabbitMQ for internal RPC and broadcasts. +- Chain as a declared Compose dependency at the inspected revision. +- Accepted-block broadcasts used to persist newly accepted blocks and receipts. +- Direct block-add requests supported by the internal RPC contract. + +## Outputs, RPCs, and broadcasts + +The pinned protocol revision defines Block Store RPC methods for: + +- reading blocks by block ID; +- reading blocks by height; +- adding a block; and +- reading the highest stored block. + +The service is primarily a broadcast consumer and RPC provider. No +Block-Store-owned consensus broadcast was identified in the inspected +foundation. + +## Persistent state + +The inspected implementation uses BadgerDB to store blocks, receipts, and lookup +metadata. This data is durable blockchain history, but the service does not +decide which block passes consensus validation. + +The relationship between accepted, forked, and irreversible blocks in storage +needs explicit release-level verification before it is explained publicly. + +## Failure and consistency considerations + +- P2P synchronization and historical queries can fail or lag when Block Store is + unavailable. +- The highest stored block and Chain's current head describe different service + states and can temporarily differ. +- Redelivered accepted-block messages must not corrupt block indexes. +- A successful write to Block Store does not by itself make a block canonical. +- Database compatibility and recovery are operational concerns; procedures + belong in Node Operators. + +## Verification before publication + +- Confirm how blocks on competing forks are represented and retrieved. +- Confirm message redelivery and write-idempotency behavior. +- Verify the meaning of “highest block” under forks and partial catch-up. +- Verify which receipts and metadata are persisted in the selected release. +- Confirm whether any current service bypasses accepted-block broadcasts and + uses the add-block RPC in normal operation. + +## Versioned sources + +- [`koinos-block-store` inspected revision](https://github.com/koinos/koinos-block-store/tree/2bb94558df61c71eb241002635444cdddce0843c) +- [`koinos-proto` Block Store RPC definitions](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/block_store/block_store_rpc.proto) +- [`koinos-proto` block broadcast definitions](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/broadcast/broadcast.proto) +- [Pinned Compose service](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/drafts/architecture/microservices/services/chain.md b/drafts/architecture/microservices/services/chain.md new file mode 100644 index 00000000..e47cc5ae --- /dev/null +++ b/drafts/architecture/microservices/services/chain.md @@ -0,0 +1,87 @@ +# Chain + +> [!IMPORTANT] +> **Internal draft — not published.** Consensus-sensitive descriptions require +> review against a coherent release and confirmation by Koinos maintainers. + +## Purpose + +Chain is the authoritative service for Koinos consensus validation and +blockchain state. It validates transactions and blocks, executes contracts, +applies the protocol's fork-choice rules, and exposes state-dependent queries. + +Other services can store artifacts or derived views, but they do not replace +Chain's decision about accepted canonical state. + +## Dependencies and inputs + +- RabbitMQ for internal protobuf RPC and broadcasts. +- Submitted transactions and blocks from P2P, Block Producer, API gateways, or + other authorized internal callers. +- Protocol rules, system calls, and contract execution behavior provided by the + matching Koinos runtime and system-contract revisions. +- Previously committed chain state and block context needed during validation. + +The inspected implementation also observes accepted-block messages as part of +its indexing and catch-up behavior. The exact startup sequence and replay +contract need release-level verification. + +## Outputs, RPCs, and broadcasts + +The pinned protocol revision defines Chain RPC methods for: + +- submitting a block or transaction; +- reading head information, chain ID, and fork heads; +- reading a contract and account nonce or resource-credit state; +- reading resource limits; +- invoking a system call; and +- proposing a block for validation before submission. + +Not every internal method is necessarily exposed by every public API gateway. + +The inspected Chain service emits broadcasts for accepted blocks, irreversible +blocks, fork heads, accepted transactions, failed transactions, and contract +events. + +## Persistent state + +The inspected implementation uses RocksDB-backed state storage. Chain owns the +consensus-critical state required to validate subsequent transactions and +blocks. Its persistent data must be compatible with the exact executable and +protocol revision. + +Architecture documentation should describe ownership and consistency, while +backup, restore, reindex, and resync procedures remain in Node Operators. + +## Failure and consistency considerations + +- Chain unavailability prevents authoritative validation and state-dependent + service calls. +- A response from an API gateway is only as current as the Chain instance it + reached. +- Non-irreversible blocks can be displaced by a fork; consumers must not treat + acceptance as irreversibility. +- A block broadcast and the catch-up state of every downstream index are + separate conditions. +- Incompatible state, runtime, or system-contract versions are + consensus-sensitive and cannot be resolved by an API-layer retry. +- Running multiple writers against the same state requires explicit support; + it must not be inferred from the microservice design. + +## Verification before publication + +- Pin a compatible Koinos release, runtime, system-contract, and proto set. +- Confirm the fork-choice and irreversible-block terminology intended for the + target audience. +- Map internal Chain methods to the methods deliberately exposed through + JSON-RPC, gRPC, and REST. +- Confirm the accepted-block subscription, replay, and startup behavior. +- Obtain maintainer review for any description of validation, execution, + receipts, resource accounting, or fork resolution. + +## Versioned sources + +- [`koinos-chain` inspected revision](https://github.com/koinos/koinos-chain/tree/0ae99eced8b585c4145424e9c2a28f667796cc66) +- [`koinos-chain` service implementation](https://github.com/koinos/koinos-chain/blob/0ae99eced8b585c4145424e9c2a28f667796cc66/src/koinos_chain.cpp) +- [`koinos-proto` Chain RPC definitions](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/chain/chain_rpc.proto) +- [`koinos-proto` broadcast definitions](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/broadcast/broadcast.proto) diff --git a/drafts/architecture/microservices/services/contract-meta-store.md b/drafts/architecture/microservices/services/contract-meta-store.md new file mode 100644 index 00000000..09d646c2 --- /dev/null +++ b/drafts/architecture/microservices/services/contract-meta-store.md @@ -0,0 +1,64 @@ +# Contract Meta Store + +> [!IMPORTANT] +> **Internal draft — not published.** Contract metadata extraction and fork +> behavior must be verified against a coherent release. + +## Purpose + +Contract Meta Store builds a query index for deployed contract metadata, +including ABI information. It lets API consumers discover contract interfaces +without making Chain maintain a separate metadata-oriented index. + +The service indexes on-chain observations; it does not make an ABI correct, +safe, or canonical independently of the block and contract state from which it +was derived. + +## Dependencies and inputs + +- RabbitMQ for internal RPC and accepted-block broadcasts. +- Chain as a declared Compose dependency. +- Accepted blocks, receipts, and contract events or operations needed to + recognize metadata changes. + +## Outputs, RPCs, and broadcasts + +The pinned protocol revision defines `get_contract_meta`, which returns metadata +for a requested contract ID according to the RPC schema. + +No Contract-Meta-Store-owned architecture broadcast was identified in the +inspected foundation. + +## Persistent state + +The inspected implementation uses BadgerDB for its derived metadata index. The +index can lag Chain and may require rebuild or reconciliation after changes in +the selected fork. + +ABI meaning and serialization belong in the ABI and Serialization architecture +pages; this service page should focus on how the metadata becomes queryable. + +## Failure and consistency considerations + +- A missing ABI can mean no metadata was published, the contract is not on the + selected fork, or the index has not caught up. +- Metadata observed before irreversibility can be affected by a fork. +- Redelivery and replay must not produce conflicting versions. +- Contract updates need a clearly defined “current metadata” rule. +- Consumers should not use metadata presence as a substitute for contract or + transaction validation. + +## Verification before publication + +- Confirm exactly which operations or events create and update metadata. +- Verify fork rollback, catch-up, replay, and write-idempotency behavior. +- Define the response semantics for missing, malformed, and superseded ABI data. +- Confirm whether historical metadata versions are retained. +- Coordinate terminology with the future ABI and Smart Contracts pages. + +## Versioned sources + +- [`koinos-contract-meta-store` inspected revision](https://github.com/koinos/koinos-contract-meta-store/tree/64e803e1db1a9bb2946ae379ddad0e5611442ec5) +- [`koinos-proto` Contract Meta Store RPC definitions](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/contract_meta_store/contract_meta_store_rpc.proto) +- [`koinos-proto` accepted-block and contract-event broadcasts](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/broadcast/broadcast.proto) +- [Pinned Compose service](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/drafts/architecture/microservices/services/grpc.md b/drafts/architecture/microservices/services/grpc.md new file mode 100644 index 00000000..f14073c7 --- /dev/null +++ b/drafts/architecture/microservices/services/grpc.md @@ -0,0 +1,65 @@ +# gRPC + +> [!IMPORTANT] +> **Internal draft — not published.** The generated service surface and public +> exposure model require release-level verification. + +## Purpose + +gRPC is a typed protobuf gateway to selected Koinos RPC services. It accepts +gRPC calls, forwards corresponding protobuf RPC requests through RabbitMQ, and +returns typed protobuf responses. + +It provides a client protocol and schema, not an independent source of chain +truth. + +## Dependencies and inputs + +- RabbitMQ for internal RPC. +- Chain as a declared Compose dependency. +- The public gRPC service definitions in `koinos-proto`. +- Any target microservice needed by an exposed method. +- gRPC client requests encoded with the compatible protobuf schema. + +The pinned public service definition includes selected methods from Account +History, Block Store, Chain, Contract Meta Store, Mempool, P2P, and Transaction +Store. It does not automatically expose every internal RPC method. + +## Outputs, RPCs, and broadcasts + +- Typed gRPC responses and status errors. +- Internal protobuf RPC requests to the corresponding target services. +- Method allowlist and denylist behavior in the inspected implementation. + +The gateway does not originate consensus broadcasts. + +## Persistent state + +The inspected gRPC service does not own chain or derived-index databases. Its +state is limited to gateway configuration and in-flight protocol handling. + +## Failure and consistency considerations + +- A reachable gRPC endpoint can still return target-service unavailability. +- Schema incompatibility can break clients even when the transport is healthy. +- Reads across services can reflect different catch-up positions. +- Retrying a submission after a timeout is method-specific and cannot be + assumed safe from the gateway layer alone. +- Public-interface security and transport configuration must be verified and + documented in Node Operators, not inferred from source defaults. + +## Verification before publication + +- Regenerate or inspect the public gRPC surface for the selected proto revision. +- Confirm method filtering and target-service routing. +- Test protobuf compatibility and error/status translation. +- Verify timeout, message-size, streaming, and connection-lifecycle behavior. +- Establish the intended public security and exposure model with maintainers. +- Confirm behavior when optional index services are absent or catching up. + +## Versioned sources + +- [`koinos-grpc` inspected revision](https://github.com/koinos/koinos-grpc/tree/3a94c34fa002552ef586cd1af9bfd34d175430d3) +- [`koinos-grpc` service implementation](https://github.com/koinos/koinos-grpc/blob/3a94c34fa002552ef586cd1af9bfd34d175430d3/src/koinos_grpc.cpp) +- [`koinos-proto` public gRPC services](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/services.proto) +- [Pinned Compose profile](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/drafts/architecture/microservices/services/json-rpc.md b/drafts/architecture/microservices/services/json-rpc.md new file mode 100644 index 00000000..3fa45cbe --- /dev/null +++ b/drafts/architecture/microservices/services/json-rpc.md @@ -0,0 +1,76 @@ +# JSON-RPC + +> [!IMPORTANT] +> **Internal draft — not published.** Public method exposure, filtering, and +> error behavior must be verified against the selected release. + +## Purpose + +JSON-RPC is an HTTP gateway between JSON-RPC clients and Koinos microservices. +It translates JSON requests into protobuf RPC messages, routes them to the +target internal service through RabbitMQ, and translates responses back to +JSON. + +The gateway exposes service capabilities; it does not own or validate canonical +blockchain state. + +## Dependencies and inputs + +- RabbitMQ for internal RPC. +- Chain as a declared Compose dependency. +- Protobuf service descriptors used to map JSON method names and payloads. +- Any additional target service required by an enabled method, such as Mempool, + Block Store, Transaction Store, Contract Meta Store, Account History, or P2P. +- HTTP JSON-RPC requests from clients. + +A Compose startup dependency does not guarantee that every optional target +service is available. + +## Outputs, RPCs, and broadcasts + +- HTTP JSON-RPC responses and protocol-level errors. +- Internal protobuf RPC requests addressed to the service named by the JSON-RPC + method. +- Mapping of protobuf responses and service errors back to JSON. +- Method allowlist and denylist behavior in the inspected implementation. + +JSON-RPC is not expected to originate consensus broadcasts. + +## Persistent state + +The inspected gateway does not own chain or index databases. It maintains +gateway-level configuration and runtime request state. Any cache, descriptor, +or request-lifecycle state must not be presented as authoritative blockchain +state. + +## Failure and consistency considerations + +- HTTP availability does not establish that the requested internal service is + available or caught up. +- A timeout can occur between forwarding a request and receiving its response; + retry safety depends on the target method. +- Read responses from different services can reflect different catch-up + positions. +- Method filtering affects the exposed API surface and should be intentional. +- Malformed JSON, protobuf conversion failures, internal RPC errors, and service + errors need stable error mapping for clients. +- Public exposure, authentication, TLS, rate limiting, and proxy configuration + are operational topics for Node Operators. + +## Verification before publication + +- Generate the actually exposed method set from the selected release and its + configuration. +- Confirm method naming, protobuf-to-JSON conversion, and error mapping. +- Confirm retry semantics for read and submit methods. +- Verify allowlist, denylist, request-size, and timeout behavior. +- Test behavior when an optional target service is absent or behind. +- Coordinate public API examples with the Getting Started chapter rather than + duplicating them here. + +## Versioned sources + +- [`koinos-jsonrpc` inspected revision](https://github.com/koinos/koinos-jsonrpc/tree/2c9433c67f2f60c920525a6c4bd3e15b0b51d94a) +- [`koinos-jsonrpc` request mapping](https://github.com/koinos/koinos-jsonrpc/blob/2c9433c67f2f60c920525a6c4bd3e15b0b51d94a/internal/jsonrpc.go) +- [`koinos-proto` public service definitions](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/services.proto) +- [Pinned Compose profile](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/drafts/architecture/microservices/services/mempool.md b/drafts/architecture/microservices/services/mempool.md new file mode 100644 index 00000000..962e378c --- /dev/null +++ b/drafts/architecture/microservices/services/mempool.md @@ -0,0 +1,76 @@ +# Mempool + +> [!IMPORTANT] +> **Internal draft — not published.** Pending-transaction and fork behavior are +> release-sensitive and require maintainer review before publication. + +## Purpose + +Mempool maintains the node's working set of pending transactions. It tracks +account nonces and reserved resource credits, filters transactions as chain +state changes, and supplies valid pending transactions to Block Producer. + +Mempool state is not canonical chain history. It is a fork-aware view of +transactions that might be included in a future block. + +## Dependencies and inputs + +- RabbitMQ for internal RPC and broadcasts. +- Chain for transaction validation and the current state context. +- Accepted and failed transaction broadcasts. +- Accepted and irreversible block broadcasts that change pending-transaction + validity or confirm inclusion. +- Pending transactions submitted through Chain and propagated from peers or + external API callers. + +## Outputs, RPCs, and broadcasts + +The pinned protocol revision defines methods for: + +- checking pending account resources; +- reading pending transactions, including lookup by transaction ID; +- checking an account nonce and reading a pending nonce; +- reading reserved account resource credits; and +- reading the pending transaction count. + +The inspected implementation announces mempool acceptance and emits a +Mempool-specific accepted-block routing event used by Block Producer. The exact +payload and ordering relationships need release-level verification. + +## Persistent state + +The inspected implementation uses Koinos state-database components for +fork-aware working state. Pending transactions are transient relative to +canonical chain state and may be reconstructed or discarded as blocks and forks +change. + +Public documentation must not imply that persistence guarantees transaction +inclusion. + +## Failure and consistency considerations + +- A transaction can leave the Mempool because it was included, became invalid, + conflicted with account state, expired under policy, or was evicted. +- A successful pending lookup does not guarantee future block inclusion. +- Mempool and Chain must evaluate nonces and resources against compatible state + contexts. +- Fork changes can make a previously rejected transaction valid again or a + pending transaction invalid. +- Block Producer can remain running but be unable to assemble an expected + candidate set when Mempool is unavailable or behind. + +## Verification before publication + +- Confirm admission, eviction, ordering, expiration, and capacity policy. +- Map each transaction and block broadcast to the state transition it causes. +- Confirm the role and payload of the Mempool-specific accepted-block event. +- Verify restart and reconstruction behavior. +- Confirm which Mempool RPCs are intentionally exposed through each public API. +- Obtain maintainer review for nonce and resource-reservation explanations. + +## Versioned sources + +- [`koinos-mempool` inspected revision](https://github.com/koinos/koinos-mempool/tree/3f2a276e4b3e4fa37c69031b2f6f707915644086) +- [`koinos-mempool` service implementation](https://github.com/koinos/koinos-mempool/blob/3f2a276e4b3e4fa37c69031b2f6f707915644086/src/koinos_mempool.cpp) +- [`koinos-proto` Mempool RPC definitions](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/mempool/mempool_rpc.proto) +- [`koinos-proto` transaction and block broadcasts](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/broadcast/broadcast.proto) diff --git a/drafts/architecture/microservices/services/p2p.md b/drafts/architecture/microservices/services/p2p.md new file mode 100644 index 00000000..cc11abf4 --- /dev/null +++ b/drafts/architecture/microservices/services/p2p.md @@ -0,0 +1,77 @@ +# P2P + +> [!IMPORTANT] +> **Internal draft — not published.** Peer protocol, synchronization, identity, +> and persistence details require focused verification before publication. + +## Purpose + +P2P connects a local Koinos node to other Koinos nodes. It discovers and manages +peers, exchanges blocks and transactions, reports peer status, and coordinates +block synchronization while still submitting received data to local consensus +validation. + +P2P transports network data; it does not decide that a block or transaction is +valid. + +## Dependencies and inputs + +- RabbitMQ for RPC and broadcasts within the local node. +- Chain for chain ID, head, fork information, and submission of peer data. +- Block Store for serving blocks to peers and supporting synchronization. +- Remote Koinos peers using the service's libp2p-based peer RPC and gossip + protocols. +- Local blocks and transactions that should be announced to peers after the + relevant local acceptance conditions. + +The inspected peer RPC implementation includes operations for chain ID, head +block, ancestor block ID, and block retrieval. + +## Outputs, RPCs, and broadcasts + +- Internal `get_gossip_status` RPC for observing current gossip/peer state. +- Gossip-status broadcasts consumed by interested local services. +- Peer-to-peer requests and responses for chain metadata and blocks. +- Block and transaction submissions to Chain for local validation. +- Outbound block and transaction gossip after local processing. + +Exact gossip routing, suppression, retry, and validation order must be mapped +from a compatible release before publication. + +## Persistent state + +P2P does not own canonical chain state. The inspected foundation was not +sufficient to make a durable claim about every peer, identity, or address record +persisted by current releases. + +Any persistent P2P identity or peer-store behavior must be documented only after +verification. Operational identity files and configuration belong in Node +Operators, not this page. + +## Failure and consistency considerations + +- A node can have healthy local services but no usable peers, preventing new + network data from arriving. +- P2P must compare chain IDs before treating a peer as compatible. +- Received blocks and transactions still require Chain validation. +- Peer-reported head information is not locally authoritative. +- Synchronization depends on both peer availability and local Block Store and + Chain progress. +- Restarting with a different P2P identity can affect peer continuity, but + identity management is an operator concern. + +## Verification before publication + +- Pin and describe the current peer protocol and gossip versions. +- Verify peer discovery, connection management, and synchronization phases. +- Confirm the exact conditions for outbound block and transaction gossip. +- Establish current persistence behavior for peer identity and peer records. +- Confirm chain-ID rejection, fork synchronization, retry, and ban behavior. +- Keep addresses, seeds, ports, and identity procedures in Node Operators. + +## Versioned sources + +- [`koinos-p2p` inspected revision](https://github.com/koinos/koinos-p2p/tree/e2267ba230960b5e4100c16ad84c42cfc12eec4b) +- [`koinos-proto` P2P RPC definitions](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/p2p/p2p_rpc.proto) +- [`koinos-proto` gossip-status broadcast](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/broadcast/broadcast.proto) +- [Pinned Compose service](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/drafts/architecture/microservices/services/rest.md b/drafts/architecture/microservices/services/rest.md new file mode 100644 index 00000000..e28382d4 --- /dev/null +++ b/drafts/architecture/microservices/services/rest.md @@ -0,0 +1,72 @@ +# REST + +> [!IMPORTANT] +> **Internal draft — not published.** The REST surface, transformations, cache +> behavior, and stability guarantees require dedicated verification. + +## Purpose + +REST provides HTTP resource-style endpoints, OpenAPI descriptions, and a +browser-accessible API reference for selected Koinos capabilities. At the +inspected Compose revision it is built on top of JSON-RPC rather than connecting +directly to RabbitMQ. + +REST is an API presentation layer. It does not own consensus state. + +## Dependencies and inputs + +- JSON-RPC as the declared upstream service. +- HTTP requests from applications and API explorers. +- Koilib and bundled ABI or application metadata used by the inspected + implementation to build higher-level responses. +- Optional application dependencies used for name resolution or caching, whose + exact role requires verification. + +REST is absent from the historical Koinos One microservice documents, so this +draft relies on the current official repository and Compose topology. + +## Outputs, RPCs, and broadcasts + +- REST responses derived from upstream JSON-RPC calls. +- OpenAPI/Swagger descriptions for the implemented HTTP endpoints. +- HTTP status and error translations. + +The inspected topology does not show REST publishing internal Koinos +broadcasts. + +## Persistent state + +REST does not own canonical blockchain state or the authoritative derived +indexes. The inspected repository includes application dependencies that may +support cache or name-resolution behavior. Their persistence, invalidation, and +deployment semantics must be verified before any stronger claim is published. + +## Failure and consistency considerations + +- REST availability depends on JSON-RPC and the downstream service used by each + request. +- Higher-level transformation can hide distinctions present in the underlying + protobuf or JSON-RPC response. +- Generated API descriptions can drift from runtime behavior if they are not + tested from the same revision. +- Cached or resolved values can have freshness behavior different from the + Chain head. +- Public HTTP exposure, proxying, TLS, rate limiting, and cache operation belong + in Node Operators. + +## Verification before publication + +- Inventory the generated REST/OpenAPI surface at the selected release. +- Map every endpoint to its JSON-RPC and internal-service dependencies. +- Confirm error translation, pagination, response transformation, and versioning + policy. +- Verify cache, Redis, name-resolution, and invalidation behavior where used. +- Confirm which bundled ABIs are required and how they are updated. +- Test the generated OpenAPI document against the running service. + +## Versioned sources + +- [`koinos-rest` inspected revision](https://github.com/koinos/koinos-rest/tree/d7f5bc90f11f78af9167e64913a028c00036d134) +- [`koinos-rest` application configuration](https://github.com/koinos/koinos-rest/blob/d7f5bc90f11f78af9167e64913a028c00036d134/app.config.ts) +- [Pinned Compose relationship to JSON-RPC](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) +- [`koinos-jsonrpc` inspected upstream](https://github.com/koinos/koinos-jsonrpc/tree/2c9433c67f2f60c920525a6c4bd3e15b0b51d94a) diff --git a/drafts/architecture/microservices/services/transaction-store.md b/drafts/architecture/microservices/services/transaction-store.md new file mode 100644 index 00000000..04e4238e --- /dev/null +++ b/drafts/architecture/microservices/services/transaction-store.md @@ -0,0 +1,64 @@ +# Transaction Store + +> [!IMPORTANT] +> **Internal draft — not published.** Indexing and fork behavior require +> verification against the release selected for public documentation. + +## Purpose + +Transaction Store builds a transaction lookup index from accepted blocks. It +allows callers to retrieve transactions and their associated block context by +transaction ID without making Chain own a separate query index. + +## Dependencies and inputs + +- RabbitMQ for internal RPC and accepted-block broadcasts. +- Chain as a declared Compose dependency. +- Accepted blocks and receipts used to populate transaction records. + +The service is absent from the historical Koinos One microservice documents, so +this draft relies on current official sources rather than historical prose. + +## Outputs, RPCs, and broadcasts + +The pinned protocol revision defines `get_transactions_by_id`. The response can +associate requested transaction IDs with stored transaction and block +information according to the protocol schema. + +No Transaction-Store-owned architecture broadcast was identified in the +inspected foundation. + +## Persistent state + +The inspected implementation uses BadgerDB. Its transaction lookup data is a +derived index built from blockchain artifacts and can, in principle, be +reconstructed from a verified block history. + +Rebuildability does not guarantee that a live index is complete or current. + +## Failure and consistency considerations + +- Transaction lookup can be unavailable or behind even when Chain is healthy. +- Accepted blocks that are later displaced by a fork require correct index + reconciliation. +- Redelivered broadcasts must not create conflicting transaction records. +- A “not found” response can mean absent, not yet indexed, or no longer part of + the service's selected fork unless the API contract distinguishes those + cases. +- The index must not be treated as the source of consensus truth. + +## Verification before publication + +- Confirm fork rollback and irreversible-block handling. +- Confirm catch-up, replay, and write-idempotency behavior. +- Define the completeness semantics of `get_transactions_by_id`. +- Verify which transaction receipt and block metadata fields are stored. +- Confirm whether the index is expected to be rebuildable in supported + operational workflows without documenting those workflows here. + +## Versioned sources + +- [`koinos-transaction-store` inspected revision](https://github.com/koinos/koinos-transaction-store/tree/c8d985ab1b0dd3862fd2d0099f4458ebc6e0920c) +- [`koinos-proto` Transaction Store RPC definitions](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/rpc/transaction_store/transaction_store_rpc.proto) +- [`koinos-proto` accepted-block broadcast](https://github.com/koinos/koinos-proto/blob/f3ba7c54d72ddd7b6898a0e2ab7567dcf60ccd80/koinos/broadcast/broadcast.proto) +- [Pinned Compose service](https://github.com/koinos/koinos/blob/821674672e699bf56e94d7c0e8bce122e83d1482/docker-compose.yml) diff --git a/mkdocs.yml b/mkdocs.yml index 69a8be7f..639db304 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -224,23 +224,27 @@ nav: - Architecture: - architecture/index.md - Microservices: - - architecture/microservices/koinos-chain.md - - architecture/microservices/block-store.md - - architecture/microservices/p2p.md - - architecture/microservices/mempool.md - - architecture/microservices/transaction-store.md - - architecture/microservices/block-producer.md - - architecture/microservices/json-rpc.md - - architecture/microservices/grpc.md - - architecture/microservices/contract-meta-store.md - - architecture/microservices/account-history.md - - architecture/interprocess-communication.md - - architecture/serialization.md - - architecture/smart-contracts.md - - architecture/contract-abi.md - - architecture/resources.md - - architecture/system-calls.md - - architecture/proof-of-burn.md + - Microservices overview: architecture/microservices.md + - Internal messaging: architecture/interprocess-communication.md + - Services: + - Chain: architecture/microservices/koinos-chain.md + - Block Store: architecture/microservices/block-store.md + - P2P: architecture/microservices/p2p.md + - Mempool: architecture/microservices/mempool.md + - Transaction Store: architecture/microservices/transaction-store.md + - Block Producer: architecture/microservices/block-producer.md + - JSON-RPC: architecture/microservices/json-rpc.md + - gRPC: architecture/microservices/grpc.md + - REST: architecture/microservices/rest.md + - Contract Meta Store: architecture/microservices/contract-meta-store.md + - Account History: architecture/microservices/account-history.md + - Smart contract execution: + - Smart contracts: architecture/smart-contracts.md + - Contract ABI: architecture/contract-abi.md + - System calls: architecture/system-calls.md + - Serialization: architecture/serialization.md + - Resource model: architecture/resources.md + - Proof of Burn: architecture/proof-of-burn.md - System Contracts: - system-contracts/index.md - system-contracts/tokenomics.md