diff --git a/index.mdx b/index.mdx index a610d63..c5725a4 100644 --- a/index.mdx +++ b/index.mdx @@ -5,38 +5,39 @@ 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, 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. -## 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 same spec serves two audiences: the protocol author who publishes it, and the application developer who consumes it. -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, 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 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. -## 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 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. -## Out of Scope +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. -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/) ♥️. +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 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. +Tx3 makes that knowledge a first-class, machine-readable artifact: the protocol's interface, written down. -## The Language +## What's in the toolkit -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. +- 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'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. +## Not a smart contract language -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. +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 +59,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