Merge pull request #30 from Arch-Network/brian/doc-updates

Doc updates

src/SUMMARY.md

@@ -30,13 +30,15 @@
 
 # Reference
 - [Program](program/program.md)
-    - [Account](program/account.md)
+    - [Account Structure](program/account.md)
+    - [Account Guide](program/accounts.md)
+    - [System Functions](program/system-functions.md)
     - [Entrypoint](program/entrypoint.md)
     - [Instructions and Messages](program/instructions-and-messages.md)
     - [Pubkey](program/pubkey.md)
     - [Syscall](program/syscall.md)
     - [System Instruction](program/system-instruction.md)
-    - [UTXO](program/utxo.md) 
+    - [UTXO](program/utxo.md)
 - [SDK](sdk/sdk.md)
     - [Processed Transaction](sdk/processed-transaction.md)
     - [Runtime Transaction](sdk/runtime-transaction.md)

src/program/account.md

@@ -1,4 +1,8 @@
-# Accounts
+# Account Structure
+
+> **Navigation**: [Reference](../SUMMARY.md#reference) → [Program](./program.md) → Account Structure
+>
+> For a comprehensive guide on working with accounts, see the [Account Guide](./accounts.md).
 
 Accounts are a fundamental data structure in Arch that store state and are owned by [programs]. Each account has a unique address ([pubkey]) and contains data that can be modified by its owner program.
 

src/program/accounts.md

@@ -1,7 +1,13 @@
-# Accounts in Arch Network
+# Account Guide
+
+> **Navigation**: [Reference](../SUMMARY.md#reference) → [Program](./program.md) → Account Guide
+>
+> For the core account structure and data types, see [Account Structure](./account.md).
 
 Accounts are the fundamental building blocks for state management and program interaction in Arch Network. They serve as containers for both program code and state data, bridging the gap between Bitcoin's UTXO model and modern programmable state machines.
 
+> **Note**: For detailed documentation on core system functions used to interact with accounts (like `invoke`, `new_create_account_instruction`, `add_state_transition`, and `set_transaction_to_sign`), see [System Functions](./system-functions.md).
+
 ```mermaid
 graph TD
     A[Account] --> B[Program Account]
@@ -156,6 +162,8 @@ let utxo_account = SystemInstruction::CreateAccount {
 
 ## Account Interactions
 
+Account interactions in Arch Network are facilitated through a set of core system functions. These functions handle everything from account creation to state transitions and are documented in detail in [System Functions](./system-functions.md). Below are common patterns for account interactions:
+
 ### 1. Creation Patterns
 
 ```rust,ignore

src/program/system-functions.md

@@ -0,0 +1,170 @@
+# System Functions
+
+> **Navigation**: [Reference](../SUMMARY.md#reference) → [Program](./program.md) → System Functions
+
+Core system functions that enable program interactions, account management, and state transitions in Arch Network.
+
+## Overview
+
+These functions form the foundation for program-to-program communication, account management, and state transitions in Arch Network:
+
+1. `invoke` - Cross-program invocation
+2. `new_create_account_instruction` - Account creation
+3. `add_state_transition` - State management
+4. `set_transaction_to_sign` - Transaction preparation
+
+## Detailed Function Documentation
+
+### 1. `invoke`
+```rust,ignore
+pub fn invoke(instruction: &Instruction, account_infos: &[AccountInfo]) -> ProgramResult
+```
+
+The `invoke` function enables cross-program communication and execution:
+
+- **Purpose**: Allows one program to call another program securely
+- **Key Features**:
+  - Validates account permissions
+  - Manages account borrowing
+  - Handles cross-program context
+  - Provides error handling
+
+**Example Usage**:
+```rust,ignore
+// Invoke system program to create account
+invoke(
+    &SystemInstruction::new_create_account_instruction(
+        txid.try_into().unwrap(),
+        vout,
+        account_pubkey
+    ),
+    &[account_info.clone()]
+)?;
+```
+
+### 2. `new_create_account_instruction`
+```rust,ignore
+pub fn new_create_account_instruction(
+    txid: [u8; 32],
+    vout: u32,
+    pubkey: Pubkey,
+) -> Instruction
+```
+
+Creates instructions for new account initialization:
+
+- **Purpose**: Creates new accounts with UTXO backing
+- **Key Features**:
+  - Sets up UTXO metadata
+  - Configures permissions
+  - Associates with system program
+  - Prepares initialization
+
+**Example Usage**:
+```rust,ignore
+let instruction = SystemInstruction::new_create_account_instruction(
+    txid.try_into().unwrap(),
+    0,  // vout index
+    account_pubkey,
+);
+```
+
+### 3. `add_state_transition`
+```rust,ignore
+pub fn add_state_transition(transaction: &mut Transaction, account: &AccountInfo)
+```
+
+Manages state transitions for accounts:
+
+- **Purpose**: Updates Bitcoin transactions with account changes
+- **Key Features**:
+  - Adds UTXO inputs
+  - Sets up script signatures
+  - Configures outputs
+  - Manages state
+
+**Example Usage**:
+```rust,ignore
+let mut tx = Transaction {
+    version: Version::TWO,
+    lock_time: LockTime::ZERO,
+    input: vec![],
+    output: vec![],
+};
+add_state_transition(&mut tx, account);
+```
+
+### 4. `set_transaction_to_sign`
+```rust,ignore
+pub fn set_transaction_to_sign(
+    accounts: &[AccountInfo],
+    transaction_to_sign: TransactionToSign,
+) -> ProgramResult
+```
+
+Prepares transactions for signing:
+
+- **Purpose**: Sets up transaction metadata and permissions
+- **Key Features**:
+  - Validates size limits
+  - Checks signer permissions
+  - Sets up metadata
+  - Manages requirements
+
+**Example Usage**:
+```rust,ignore
+let transaction_to_sign = TransactionToSign {
+    tx_bytes: serialized_tx,
+    inputs_to_sign: vec![
+        InputToSign {
+            signer: account.key,
+            ..Default::default()
+        }
+    ],
+};
+set_transaction_to_sign(accounts, transaction_to_sign)?;
+```
+
+## Function Flow
+
+```mermaid
+graph TD
+    A[Program Request] --> B[new_create_account_instruction]
+    B --> C[invoke]
+    C --> D[add_state_transition]
+    D --> E[set_transaction_to_sign]
+    E --> F[Bitcoin Transaction]
+    
+    subgraph "Execution Flow"
+    B --> |Initialize| G[Account Creation]
+    C --> |Execute| H[Instruction Processing]
+    D --> |Update| I[State Management]
+    E --> |Prepare| J[Transaction Signing]
+    end
+```
+
+## Best Practices
+
+1. **Validation**
+   - Always check account permissions
+   - Verify transaction limits
+   - Validate UTXO states
+   - Handle errors properly
+
+2. **State Management**
+   - Use atomic operations
+   - Maintain state consistency
+   - Handle failures gracefully
+   - Implement rollbacks
+
+3. **Security**
+   - Validate all signatures
+   - Check account ownership
+   - Verify transaction data
+   - Handle edge cases
+
+## Related Topics
+- [Accounts](./accounts.md)
+- [UTXOs](./utxo.md)
+- [Programs](./program.md)
+- [Instructions](./instructions-and-messages.md)