docs: consolidate four-chapter documentation update

.github/workflows/javascript-examples.yml

@@ -1,4 +1,4 @@
-name: JavaScript examples
+name: Documentation examples
 
 on:
   pull_request:
@@ -22,6 +22,8 @@ jobs:
     timeout-minutes: 15
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: actions/setup-node@v4
         with:
           node-version: "22"
@@ -37,5 +39,6 @@ jobs:
       - run: npm run examples:test
       - run: npm run examples:start
       - run: npm run examples:smoke
+      - run: npm run node-commands:verify
       - run: npm run docs:links
       - run: mkdocs build

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.
+- [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)

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).
 
 <div class="grid cards" markdown>
 
--   :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.
-    <br/><br/>
+    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.
-    <br/><br/>
+    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.
-    <br/><br/>
+    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.
-    <br/><br/><br/>
+    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.
-    <br/><br/><br/>
-
-    [: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.
-    <br/><br/>
+</div>
 
-    [:octicons-arrow-right-24: From KVM to native](system-calls.md)
+## Source baseline
 
-</div>
+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.