Update transactions.md from PR 1553 with link fixes

Replace the initial transactions.md with the comprehensive version from
PR 1553. Convert undefined transaction type links to section anchors to
prevent broken links until those documentation pages are created.

Author: dannywillems

website/docs/developers/transactions.md

@@ -0,0 +1,180 @@
+---
+sidebar_position: 5
+title: Introduction
+description: Understanding transaction types in the Mina protocol implementation
+slug: /developers/transactions
+---
+
+# Introduction
+
+## Overview
+
+Transactions in Mina represent state changes to the ledger. The protocol
+supports both user-initiated transactions and protocol-generated transactions,
+each serving distinct purposes in the blockchain's operation.
+
+This document provides an entry point for developers to understand how
+transactions are structured and processed in the Rust codebase.
+
+## Transaction Types
+
+The top-level `Transaction` enum represents all possible transactions in the
+Mina protocol:
+
+<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic/mod.rs#L1093-L1100 -->
+
+```rust reference title="ledger/src/scan_state/transaction_logic/mod.rs"
+https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/mod.rs#L1093-L1100
+```
+
+### User-Initiated Transactions
+
+**User Commands** are transactions submitted and signed by users:
+
+- **Payment transactions** - Transfer MINA tokens between accounts
+- **Stake delegation** - Delegate stake to block producers
+- **zkApp commands** - Execute complex multi-account zero-knowledge operations
+
+### Protocol Transactions
+
+**Protocol transactions** (also called **system transactions**) are generated
+automatically by the system:
+
+- **Fee transfers** - Distribute collected transaction fees to block producers
+- **[Coinbase rewards](./transactions/coinbase)** - Issue block production
+  rewards
+
+## Transaction Application Model
+
+Transactions in Mina are applied in two phases:
+
+### First Pass (`apply_transaction_first_pass`)
+
+The first pass validates preconditions and begins transaction application:
+
+- Validates account existence and permissions
+- Checks nonces and balances
+- Applies fee payments
+- Performs initial state changes
+- Returns `TransactionPartiallyApplied` containing transaction state
+
+**Function:**
+[`ledger/src/scan_state/transaction_logic/transaction_partially_applied.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/transaction_partially_applied.rs#L190)
+
+### Second Pass (`apply_transaction_second_pass`)
+
+The second pass completes the transaction after SNARK work:
+
+- Finalizes account updates
+- Applies protocol-specific logic
+- Updates receipt chain hashes
+- Returns final `TransactionApplied` status
+
+**Function:**
+[`ledger/src/scan_state/transaction_logic/transaction_applied.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/transaction_applied.rs)
+
+## Common Transaction Components
+
+### Fees
+
+All user-initiated transactions require fees. The `Fee` type is generated by a
+macro along with other currency types in
+[`ledger/src/scan_state/currency.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/currency.rs#L575-L578).
+
+Fees serve two purposes: they compensate block producers for including
+transactions and prevent network spam by making it economically infeasible to
+flood the network with transactions. Fees are paid by the transaction sender (or
+fee payer in zkApp commands) and distributed to block producers through fee
+transfers.
+
+### Nonces
+
+User accounts maintain nonces to prevent replay attacks. The `Nonce` type is
+generated by a macro along with other currency types in
+[`ledger/src/scan_state/currency.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/currency.rs#L575-L578).
+
+Each user-initiated transaction must specify the correct nonce, which increments
+after successful application.
+
+### Memos
+
+Transactions can include optional 32-byte memos:
+
+<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic/mod.rs#L548-L548 -->
+
+```rust reference title="ledger/src/scan_state/transaction_logic/mod.rs"
+https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/mod.rs#L548-L548
+```
+
+Memos provide auxiliary information and are included in transaction commitments.
+
+### Slots
+
+A slot is a fixed time interval in the consensus protocol during which a block
+can be produced. Slots are used to measure time in the blockchain and determine
+block production opportunities.
+
+Transactions include validity windows using slot numbers. The `Slot` type is
+generated by a macro along with other currency types in
+[`ledger/src/scan_state/currency.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/currency.rs#L575-L578).
+
+The `valid_until` field specifies when a transaction expires.
+
+## Account Creation
+
+Creating new accounts requires an account creation fee (1 MINA by default):
+
+```rust
+ConstraintConstants {
+    account_creation_fee: 1_000_000_000, // 1 MINA in nanomina
+    // ...
+}
+```
+
+The fee is deducted from the amount being transferred to the new account:
+
+- **Payments**: Sender pays `amount + fee`, receiver gets
+  `amount - account_creation_fee` (if creating account)
+- **Fee transfers**: Receiver gets `fee_amount - account_creation_fee` (if
+  creating account)
+- **Coinbase**: Receiver gets `coinbase_amount - account_creation_fee` (if
+  creating account)
+
+## Transaction Status
+
+After application, transactions have a status:
+
+<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic/mod.rs#L240-L243 -->
+
+```rust reference title="ledger/src/scan_state/transaction_logic/mod.rs"
+https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/mod.rs#L240-L243
+```
+
+Failed transactions may still consume fees in some cases (zkApp commands with
+fee payer failures).
+
+## Further Reading
+
+- [Coinbase Rewards](./transactions/coinbase) - Block production rewards
+
+Documentation for additional transaction types is coming soon:
+
+- Payment Transactions - Transferring tokens between accounts
+- Stake Delegation - Delegating stake to block producers
+- Fee Transfers - Protocol fee distribution
+- zkApp Commands - Zero-knowledge applications
+
+## Related Files
+
+- [`ledger/src/scan_state/transaction_logic/mod.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/mod.rs) -
+  Transaction type definitions
+- [`ledger/src/scan_state/transaction_logic/transaction_partially_applied.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/transaction_partially_applied.rs) -
+  First pass application
+- [`ledger/src/scan_state/transaction_logic/transaction_applied.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/transaction_applied.rs) -
+  Second pass application
+- [`ledger/src/scan_state/transaction_logic/signed_command.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/signed_command.rs) -
+  Signed command types
+- [`ledger/src/scan_state/transaction_logic/zkapp_command/`](https://github.com/o1-labs/mina-rust/tree/develop/ledger/src/scan_state/transaction_logic/zkapp_command) -
+  zkApp command implementation
+- [`ledger/src/scan_state/currency.rs`](https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/currency.rs) -
+  Currency types (Fee, Nonce, Slot, Amount, Balance)