From d49bb046ce540656b845e337b48abed2414b80a0 Mon Sep 17 00:00:00 2001 From: Santiago Date: Thu, 14 May 2026 16:07:28 -0300 Subject: [PATCH 1/3] refactor: reframe introduction as the OpenAPI of UTxO Promote the interface-description framing to the lead of the docs index and reorganise the page into Two sides of the workflow / Why UTxO protocols need this / What's in the toolkit / Where the OpenAPI analogy ends / Not a smart contract language. CardGrids preserved verbatim. Also add a one-line positioning sentence to the language guide so it reads as the authoring face of Tx3. Co-Authored-By: Claude Opus 4.7 (1M context) --- index.mdx | 41 ++++++++++++++++++++++------------------- language/index.mdx | 2 +- 2 files changed, 23 insertions(+), 20 deletions(-) diff --git a/index.mdx b/index.mdx index a610d63..ddd9254 100644 --- a/index.mdx +++ b/index.mdx @@ -5,38 +5,41 @@ sidebar: order: 1 --- -import { Aside, LinkCard, CardGrid } from '@astrojs/starlight/components'; +import { LinkCard, CardGrid } from '@astrojs/starlight/components'; -Tx3 is a toolkit for authoring and interacting with UTxO protocols. Think of "UTxO Protocol" as the API to your dApp. The best analogy we have is to think of Tx3 as the "Open API" for blockchain. +Tx3 is an interface description format for UTxO blockchain protocols — the OpenAPI of UTxO — plus the tooling to author and consume those interfaces. Authors publish a spec that declares what their protocol exposes; consumers read that spec and generate typed clients to build the transactions it accepts. -## Rationale +## Two sides of the workflow -In account-based blockchains, dapps are primarily defined by smart contracts with explicit function interfaces that represent user interactions and state mutations. These dapps have a clear API surface that can be used by different parties to interact with its business logic. +The format is one half of the story. The toolchain is the other. -The deterministic nature of the UTxO approach is a great property, but it has a drawback: the interface of a dapp is not explicit, there's nothing describing how the different parties can interact with it. Dapps are defined by transaction patterns that represent deterministic "state transitions". A party interacting with an UTxO-based dapp has to understand the underlying business logic in order to construct transactions representing their intents. +**Authoring.** Protocol authors write a `.tx3` file declaring the parties involved, the assets at stake, the transaction templates a user can invoke, and the rules each one must satisfy. The Tx3 toolchain parses, type-checks, and analyses the file, runs it against a local devnet, and emits a publishable interface artifact (the TII). -This is why we need a strict but flexible mechanism to describe patterns of transactions (which we'll call transaction templates) that dapp authors can use to convey the interface of their dapp and dapp consumers can use to interact with it. +**Consuming.** Application developers point at a `.tx3` source or its compiled intermediate representation (the TIR) and get typed SDKs in TypeScript, Rust, Go, and Python. At runtime, the SDKs speak the Transaction Resolver Protocol (TRP) to a backend that materialises each transaction, signs it, submits it, and waits for inclusion. -## Scope +## Why UTxO protocols need this -- a DSL (Domain Specific Language) to describe the interface of your UTxO protocol. -- a runtime for interacting with UTxO protocols through the use of these interface definitions. -- a codegen framework for creating strongly-typed clients for UTxO protocols. -- a set of tools for authoring, testing and managing UTxO protocols. +In account-based chains, a contract has an explicit ABI: function signatures describe how to interact with it, and consumers can build against them directly. UTxO chains are different. A dApp is a set of validators that accept or reject transactions; nothing in the chain tells you which UTxOs to spend, which datums to attach, which redeemers to supply, which scripts to witness. That knowledge usually lives in the protocol author's head, or in a hand-written SDK that consumers have to reverse-engineer. -## Out of Scope +Tx3 makes that knowledge a first-class, machine-readable artifact: the protocol's interface, written down. -Tx3 is NOT meant to be a smart contract language, the idea if for devs to continue building on-chain validators using their favorite languages, we love [Aiken](https://aiken-lang.org/) ♥️. +## What's in the toolkit -Tx3 is meant to complement existing languages and tools, not replace them. It positions itself at a higher level of abstraction, describing how user interact interact with validators by constructing the required transactions off-chain. +- A declarative source format (`.tx3`) for describing the interface of a UTxO protocol. +- The `trix` CLI — package manager, build system, local devnet, and test runner. +- An interface artifact (TII) and an intermediate representation (TIR) that downstream tools consume. +- A codegen framework that produces strongly-typed clients in TypeScript, Rust, Go, and Python. +- The Transaction Resolver Protocol (TRP) — a wire protocol that backends speak to materialise, sign, and submit transactions described by a TIR. -## The Language +## Where the OpenAPI analogy ends -Tx3 is a DSL (Domain Specific Language) for describing the interface of UTxO blockchain protocols using a declarative style and basic functional expressions. It allows you to describe user intents in the form of transaction templates that abstract away the transaction building process as high-level function calls. +OpenAPI describes the shape of an HTTP call; constructing the call itself is trivial. On a UTxO chain, constructing the transaction is the hard part — UTxO selection, balancing, witnessing, fee estimation, change handling. Tx3's codegen isn't typed request/response stubs; it's a working transaction builder. The spec is also the executable. -The language's narrow focus allows it to be highly opinionated and tightly integrated with core UTxO blockchain concepts. Instead of abstracting away blockchain-specific details, Tx3 embraces them - concepts fundamental to UTxO blockchains like inputs, outputs, datums, and redeemers are treated as first-class citizens in the language. This deep integration enables more natural and expressive ways to work with these concepts. +This is also why Tx3 treats UTxO-specific concepts — inputs, outputs, datums, redeemers, mint and burn — as first-class citizens in the source format, rather than hiding them behind a chain-agnostic abstraction. The transactions Tx3 generates are the transactions consumers send to the chain. -A key concept in Tx3 is the distinction between concrete transactions and transaction templates. While a transaction represents a specific state transition, a template is a function - it defines a pattern that can generate many different concrete transactions based on parameters provided at runtime. This parameterization is what makes templates so powerful for defining reusable transaction patterns. +## Not a smart contract language + +Tx3 does not replace on-chain validators. Write those in your favourite language for the job — we love [Aiken](https://aiken-lang.org/) ♥️. Tx3 sits at a higher level of abstraction, describing how off-chain code interacts with on-chain validators by constructing the transactions they accept. ## Learning Tx3 @@ -58,4 +61,4 @@ If you're looking to dive deeper into Tx3, we have a comprehensive guide that co How Tx3 works under the hood - \ No newline at end of file + diff --git a/language/index.mdx b/language/index.mdx index acf4acf..f33b999 100644 --- a/language/index.mdx +++ b/language/index.mdx @@ -7,7 +7,7 @@ sidebar: import { LinkCard } from "@astrojs/starlight/components" -This guide is a tour of the Tx3 language: the keywords you write at the top level, the building blocks of a transaction template, and the expression forms you use to describe values. +The Tx3 language is the source format you write to publish a protocol's interface. This guide tours that language: the keywords you write at the top level, the building blocks of a transaction template, and the expression forms you use to describe values. ## Protocol From 83257c3d0172e6a6ff7a01824bedd00390b0dc7e Mon Sep 17 00:00:00 2001 From: Santiago Date: Thu, 14 May 2026 19:37:13 -0300 Subject: [PATCH 2/3] refactor: drop OpenAPI references, recast as EVM-ABI parallel Remove OpenAPI from the lead sentence and delete the "Where the OpenAPI analogy ends" section. Rewrite "Why UTxO protocols need this" so the EVM ABI is the primary analogy and OpenAPI is mentioned as a parallel from the web layer. Also folds in the in-flight wording tweaks to the lead and to the Two-sides section. Co-Authored-By: Claude Opus 4.7 (1M context) --- index.mdx | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/index.mdx b/index.mdx index ddd9254..965cb5b 100644 --- a/index.mdx +++ b/index.mdx @@ -7,19 +7,21 @@ sidebar: import { LinkCard, CardGrid } from '@astrojs/starlight/components'; -Tx3 is an interface description format for UTxO blockchain protocols — the OpenAPI of UTxO — plus the tooling to author and consume those interfaces. Authors publish a spec that declares what their protocol exposes; consumers read that spec and generate typed clients to build the transactions it accepts. +Tx3 is an interface description format for UTxO blockchain protocols, plus the tooling to author and consume those interfaces. Protocol authors define a spec that declares what their protocol exposes; consumers read that spec and generate typed clients to build the transactions it accepts. ## Two sides of the workflow The format is one half of the story. The toolchain is the other. -**Authoring.** Protocol authors write a `.tx3` file declaring the parties involved, the assets at stake, the transaction templates a user can invoke, and the rules each one must satisfy. The Tx3 toolchain parses, type-checks, and analyses the file, runs it against a local devnet, and emits a publishable interface artifact (the TII). +**Authoring.** Protocol authors write a `.tx3` file declaring the parties involved, the assets at stake, the transaction templates a user can invoke, and the rules each one must satisfy. The Tx3 toolchain parses, type-checks, and analyses the file, and emits a publishable interface artifact (the TII). -**Consuming.** Application developers point at a `.tx3` source or its compiled intermediate representation (the TIR) and get typed SDKs in TypeScript, Rust, Go, and Python. At runtime, the SDKs speak the Transaction Resolver Protocol (TRP) to a backend that materialises each transaction, signs it, submits it, and waits for inclusion. +**Consuming.** Application developers point at a compiled interface (the `.tii` file) and get typed SDKs in TypeScript, Rust, Go, and Python. At runtime, the SDKs speak the Transaction Resolver Protocol (TRP) to a backend that turns the invocation into an un-signed transaction. ## Why UTxO protocols need this -In account-based chains, a contract has an explicit ABI: function signatures describe how to interact with it, and consumers can build against them directly. UTxO chains are different. A dApp is a set of validators that accept or reject transactions; nothing in the chain tells you which UTxOs to spend, which datums to attach, which redeemers to supply, which scripts to witness. That knowledge usually lives in the protocol author's head, or in a hand-written SDK that consumers have to reverse-engineer. +EVM contracts publish an ABI: a machine-readable description of the functions a consumer can call, the arguments each takes, and what each returns. With the ABI in hand, anyone can build a working client. Web APIs solve the same problem at a different layer with OpenAPI — same idea, same payoff: the interface is data, not lore. + +UTxO chains have nothing equivalent. A dApp is a set of validators that accept or reject transactions; nothing in the chain tells you which UTxOs to spend, which datums to attach, which redeemers to supply, which scripts to witness. That knowledge usually lives in the protocol author's head, or in a hand-written SDK that consumers have to reverse-engineer. Tx3 makes that knowledge a first-class, machine-readable artifact: the protocol's interface, written down. @@ -31,12 +33,6 @@ Tx3 makes that knowledge a first-class, machine-readable artifact: the protocol' - A codegen framework that produces strongly-typed clients in TypeScript, Rust, Go, and Python. - The Transaction Resolver Protocol (TRP) — a wire protocol that backends speak to materialise, sign, and submit transactions described by a TIR. -## Where the OpenAPI analogy ends - -OpenAPI describes the shape of an HTTP call; constructing the call itself is trivial. On a UTxO chain, constructing the transaction is the hard part — UTxO selection, balancing, witnessing, fee estimation, change handling. Tx3's codegen isn't typed request/response stubs; it's a working transaction builder. The spec is also the executable. - -This is also why Tx3 treats UTxO-specific concepts — inputs, outputs, datums, redeemers, mint and burn — as first-class citizens in the source format, rather than hiding them behind a chain-agnostic abstraction. The transactions Tx3 generates are the transactions consumers send to the chain. - ## Not a smart contract language Tx3 does not replace on-chain validators. Write those in your favourite language for the job — we love [Aiken](https://aiken-lang.org/) ♥️. Tx3 sits at a higher level of abstraction, describing how off-chain code interacts with on-chain validators by constructing the transactions they accept. From 51439a12f4cc80f7777d6ce1a1da4a4b62b0549d Mon Sep 17 00:00:00 2001 From: Santiago Date: Fri, 15 May 2026 08:17:40 -0300 Subject: [PATCH 3/3] refactor: split Why-UTxO into OpenAPI then EVM-ABI paragraphs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Lead with OpenAPI as the Web2 solution and follow with the EVM ABI as the contract-layer solution, in two distinct paragraphs. Also replace the misleading "format vs toolchain" lead-in to the Two-sides section with one that names the actual contrast — author vs consumer. --- index.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/index.mdx b/index.mdx index 965cb5b..c5725a4 100644 --- a/index.mdx +++ b/index.mdx @@ -11,7 +11,7 @@ Tx3 is an interface description format for UTxO blockchain protocols, plus the t ## Two sides of the workflow -The format is one half of the story. The toolchain is the other. +The same spec serves two audiences: the protocol author who publishes it, and the application developer who consumes it. **Authoring.** Protocol authors write a `.tx3` file declaring the parties involved, the assets at stake, the transaction templates a user can invoke, and the rules each one must satisfy. The Tx3 toolchain parses, type-checks, and analyses the file, and emits a publishable interface artifact (the TII). @@ -19,7 +19,9 @@ The format is one half of the story. The toolchain is the other. ## Why UTxO protocols need this -EVM contracts publish an ABI: a machine-readable description of the functions a consumer can call, the arguments each takes, and what each returns. With the ABI in hand, anyone can build a working client. Web APIs solve the same problem at a different layer with OpenAPI — same idea, same payoff: the interface is data, not lore. +In Web2, an HTTP API is described with OpenAPI: a machine-readable spec listing every endpoint, the shape of each request, and the shape of each response. With that spec in hand, any consumer can generate a typed client and start calling the API without reading the server's source. + +The EVM ecosystem solves the same problem at the contract layer. Every contract publishes an ABI — a machine-readable description of the functions a consumer can call, the arguments each takes, and what each returns. The interface is data, not lore. UTxO chains have nothing equivalent. A dApp is a set of validators that accept or reject transactions; nothing in the chain tells you which UTxOs to spend, which datums to attach, which redeemers to supply, which scripts to witness. That knowledge usually lives in the protocol author's head, or in a hand-written SDK that consumers have to reverse-engineer.