solace 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73c15e6b362288fa1f3be0fd2793fcf43aff390deabe20f3264f22550cb67734
-  data.tar.gz: 1b036900c1306c1af4f4c0887a625d6a633a7cf4276c79c1a8b61754d7ffe593
+  metadata.gz: 5ea64862833bb39232a5157ed5d29387f8fa1e3780aeae55fcd1481592060d90
+  data.tar.gz: 6a62d0efc8eaaf900800168c5eaa6580b769460f0aaf77f104679fe99bbbcd74
 SHA512:
-  metadata.gz: 422a09d627bbf0e9bb59f3183f4a1ad34904a14996291555ff7c83717554c0915c4ba1d93c689b852cb9d9fab024cfd0e491c0443b332a6dc6f448028c48e000
-  data.tar.gz: a185276e03d031c72c7a78b11db5fd3a9b1d1fa6388758b41c20fad66241aa14b44e5188caace7d0bffaf498c03834d4fe73461754834c3a33e412a13544bf1c
+  metadata.gz: 117e324eb46561a5a51e7dd4773d3b09a6e4d00e6c5b12d9c23c7848889e5a6f877c40da08fb726c4ae766313b5c37988e2cb4287e21b2360cee9530a2a2398a
+  data.tar.gz: f0622e37fd2e1d45424d1e9257705a5c084a1b8878742ed12d6cbf1f97fea568ac7876af673c64c8299653e3a65e072247663e5cb5957454e35cd82b61e68b99

data/CHANGELOG

@@ -16,6 +16,18 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 ### Fixed
 ```
 
+## [WIP] - yyyy-mm-dd
+  
+### Added
+1. 
+
+### Changed
+1. Change `private_key` method on Keypair to `pivate_key_bytes`
+2. Change docs on most methods to include an `@example` section.
+3. Change README to include a practical example of using composers.
+ 
+### Fixed
+
 ## [0.0.3] - 2025-07-30
   
 ### Added

data/README.md

@@ -1,17 +1,18 @@
 # Solace Ruby SDK Documentation
+A Ruby SDK for the Solana blockchain.
 
 ## Overview
 
-**Solace** is a comprehensive Ruby SDK for interacting with the Solana blockchain. It provides both low-level building blocks and high-level abstractions for creating, signing, and sending Solana transactions. The library follows Ruby conventions while maintaining compatibility with Solana's binary protocols.
+Solace is a comprehensive Ruby SDK for interacting with the Solana blockchain. It provides both low-level building blocks and high-level abstractions for composing, signing, and sending Solana transactions. The library aims to follow Ruby conventions while maintaining compatibility with Solana's binary protocols.
 
 ## Architecture
 
 The Solace SDK is organized into several key layers:
 
-### 1. **Core Primitives** (Low-Level)
+### 1. **Core Classes** (Low-Level)
 - **Keypair/PublicKey**: Ed25519 cryptographic operations
 - **Connection**: RPC client for Solana nodes
-- **Transaction/Message/Instruction**: Transaction building blocks
+- **Transaction/Message/Instruction/AddressLookupTable**: Transaction building blocks
 - **Serializers**: Binary serialization/deserialization system
 
 ### 2. **Instruction Builders** (Low-Level)
@@ -19,96 +20,32 @@ The Solace SDK is organized into several key layers:
 - Handle binary data encoding and account indexing
 - Located in `lib/solace/instructions/`
 
-### 3. **Program Clients** (High-Level)
+### 3. **Composers** (High-Level)
+- Convenient interfaces for composing transactions and instructions
+- Handle account ordering and header calculations for transactions
+- Located in `lib/solace/composers`
+
+### 3. **Programs** (High-Level)
 - Convenient interfaces for interacting with on-chain programs
 - Handle transaction assembly, signing, and submission
 - Located in `lib/solace/programs/`
 
-### 4. **Utilities** (Supporting)
+### 4. **Utilities** (Support modules & classes)
 - **Codecs**: Base58/Base64 encoding, compact integers, little-endian encoding
 - **PDA**: Program Derived Address generation
 - **Curve25519**: Native curve operations via FFI
+- **More...**: Checkout `lib/solace/utils` 
 
 ## Core Components
 
-### Keypair
-
-The `Solace::Keypair` class represents Ed25519 keypairs for signing transactions.
-
-```ruby
-# Generate a new random keypair
-keypair = Solace::Keypair.generate
-
-# Create from seed (32 bytes)
-seed = SecureRandom.random_bytes(32)
-keypair = Solace::Keypair.from_seed(seed)
-
-# Create from secret key (64 bytes)
-keypair = Solace::Keypair.from_secret_key(secret_key_bytes)
-
-# Usage
-puts keypair.address          # Base58 public key
-signature = keypair.sign(message)  # Sign binary data
-```
-
-**Key Features:**
-- Ed25519 signature support via RbNaCl
-- Base58 address encoding
-- Secure random generation
-- Compatible with Solana's key format
-
-### PublicKey
-
-The `Solace::PublicKey` class represents Solana public keys with utility methods.
-
-```ruby
-# Create from bytes
-pubkey = Solace::PublicKey.new(32_byte_array)
-
-# Usage
-puts pubkey.to_base58    # Base58 representation
-puts pubkey.to_s         # Same as to_base58
-bytes = pubkey.to_bytes  # Get raw bytes
-```
-
-**Key Features:**
-- 32-byte Ed25519 public keys
-- Base58 encoding/decoding
-- PDA (Program Derived Address) support via mixin
-- Equality comparison
-
-### Connection
-
-The `Solace::Connection` class provides RPC communication with Solana nodes.
-
-```ruby
-# Connect to local validator (default = http://localhost:8899)
-connection = Solace::Connection.new
-
-# Connect to devnet or other RPC nodes
-connection = Solace::Connection.new('https://api.devnet.solana.com')
-
-# RPC methods
-balance = connection.get_balance(pubkey)
-blockhash = connection.get_latest_blockhash
-account_info = connection.get_account_info(pubkey)
-signature = connection.send_transaction(transaction)
-
-# Airdrop (devnet/testnet only)
-response = connection.request_airdrop(pubkey, 1_000_000_000) # 1 SOL
-connection.wait_for_confirmed_signature { response['result'] }
-```
-
-**Key Features:**
-- JSON-RPC 2.0 client
-- Automatic request ID generation
-- Built-in error handling
-- Support for all major RPC methods
-- Transaction confirmation waiting
-
 ### Transaction & Message
 
-Transactions contain a message and signatures. Messages contain instructions and metadata.
+Transactions contain a message and signatures. Messages contain instructions and metadata. This core class is as simple as possible and provide the lowest level of abstraction for building and sending transactions. A developer is expected to:
+
+1. Manually fill and order the accounts array
+2. Manually fill and order the instructions array
+3. Manually calculate the header
+4. ...did I forget to say manually?
 
 ```ruby
 # Create a message
@@ -143,7 +80,11 @@ signature = connection.send_transaction(transaction.serialize)
 
 ### Instruction
 
-Instructions represent individual operations within a transaction.
+Instructions represent individual operations within a transaction. Like messages, instructions are as simple as possible and provide the lowest level of abstraction for building and sending transactions. A developer is expected to:
+
+1. Manually fill and order the accounts indices array
+2. Manually specify the program index
+3. Manually specify the data
 
 ```ruby
 instruction = Solace::Instruction.new(
@@ -166,11 +107,9 @@ instruction.data # => [2, 0, 0, 0] + amount_bytes
 
 ## Low-Level Instruction Builders
 
-Instruction builders are service objects that create specific instruction types. They handle the binary encoding required by Solana programs.
+Given that the low-level instruction class is fully available, it's easy to build higher-level instruction builders that wrap the low-level instruction class. These builders are service objects that create specific instruction types. They handle the binary encoding required by Solana programs.
 
-### System Program Instructions
-
-#### Transfer Instruction
+For example, the SystemProgram::TransferInstruction builder is a service object that creates and returns a Solace::Instruction object with the correct program index, accounts indices, and data for a System Program solana transfer.
 
 ```ruby
 # Build a SOL transfer instruction
@@ -182,71 +121,33 @@ transfer_ix = Solace::Instructions::SystemProgram::TransferInstruction.build(
 )
 ```
 
-#### Create Account Instruction
-
-```ruby
-# Build account creation instruction
-create_ix = Solace::Instructions::SystemProgram::CreateAccountInstruction.build(
-  from_index: 0,              # Payer account index
-  new_account_index: 1,       # New account index
-  system_program_index: 2,    # System program index
-  lamports: rent_lamports,    # Rent-exempt amount
-  space: 165,                 # Account data size
-  owner: token_program_id     # Owning program
-)
-```
-
-### SPL Token Instructions
-
-#### Initialize Mint Instruction
-
-```ruby
-# Initialize a new token mint
-init_mint_ix = Solace::Instructions::SplToken::InitializeMintInstruction.build(
-  mint_account_index: 1,      # Mint account index
-  rent_sysvar_index: 2,       # Rent sysvar index
-  program_index: 3,           # Token program index
-  decimals: 6,                # Token decimals
-  mint_authority: authority_pubkey,
-  freeze_authority: freeze_pubkey  # Optional
-)
-```
-
-#### Mint To Instruction
+Solace includes a number of these, and you can build your own as well.
 
-```ruby
-# Mint tokens to an account
-mint_to_ix = Solace::Instructions::SplToken::MintToInstruction.build(
-  amount: 1_000_000,          # Amount to mint
-  mint_index: 0,              # Mint account index
-  destination_index: 1,       # Destination token account
-  mint_authority_index: 2,    # Mint authority index
-  program_index: 3            # Token program index
-)
-```
-
-#### Transfer Instruction
-
-```ruby
-# Transfer tokens between accounts
-transfer_ix = Solace::Instructions::SplToken::TransferInstruction.build(
-  amount: 500_000,            # Amount to transfer
-  source_index: 0,            # Source token account
-  destination_index: 1,       # Destination token account
-  owner_index: 2,             # Owner/authority index
-  program_index: 3            # Token program index
-)
-```
+- `Solace::Instructions::SystemProgram::TransferInstruction`
+- `Solace::Instructions::SystemProgram::CreateAccountInstruction`
+- `Solace::Instructions::SplToken::InitializeMintInstruction`
+- `Solace::Instructions::SplToken::InitializeAccountInstruction`
+- `Solace::Instructions::SplToken::MintToInstruction`
+- `Solace::Instructions::SplToken::TransferInstruction`
+- `Solace::Instructions::SplToken::TransferCheckedInstruction`
+- `Solace::Instructions::AssociatedTokenAccount::CreateAssociatedTokenAccountInstruction`
 
 **Common Patterns:**
 - All builders use `.build()` class method
+- All builders use `.data()` method to specify the instruction data
+- All builders use named parameters and `_index` suffix for account indices
+- All builders use a `program_index` parameter to specify the program index
 - Account indices reference the transaction's accounts array
 - Binary data encoding handled automatically
 - Instruction-specific data layouts documented in comments
 
-## High-Level Program Methods
+## High-Level Program Classes
+
+**WARNING: Programs will probably get deprecated in favor of composers in the future.**
+
+Now that we have the mid-level instruction builders, we can create high-level program classes that provide convenient interfaces for common operations, handling transaction assembly, signing, and submission.
 
-Program clients provide convenient interfaces for common operations, handling transaction assembly, signing, and submission.
+For example, the `Solace::Programs::SplToken` class provides a high-level interface for interacting with the SPL Token Program.
 
 ### SPL Token Program
 
@@ -255,31 +156,34 @@ Program clients provide convenient interfaces for common operations, handling tr
 spl_token = Solace::Programs::SplToken.new(connection: connection)
 
 # Create a new token mint
-signature = spl_token.create_mint(
+response = spl_token.create_mint(
   payer: payer_keypair,
   decimals: 6,
   mint_authority: authority_keypair,
   freeze_authority: freeze_keypair,  # Optional
   mint_keypair: mint_keypair         # Optional, generates if not provided
 )
+connection.wait_for_confirmed_signature { response['result'] }
 
 # Mint tokens to an account
-signature = spl_token.mint_to(
+response = spl_token.mint_to(
   payer: payer_keypair,
   mint: mint_keypair,
   destination: token_account_address,
   amount: 1_000_000,
   mint_authority: authority_keypair
 )
+connection.wait_for_confirmed_signature { response['result'] }
 
 # Transfer tokens
-signature = spl_token.transfer(
+response = spl_token.transfer(
   payer: payer_keypair,
   source: source_token_account,
   destination: dest_token_account,
   amount: 500_000,
   owner: owner_keypair
 )
+connection.wait_for_confirmed_signature { response['result'] }
 ```
 
 **Key Features:**
@@ -291,7 +195,7 @@ signature = spl_token.transfer(
 
 ### Prepare Methods
 
-For more control, use "prepare" methods that return signed transactions without sending:
+For more control, use "prepare" methods that return signed transactions without sending it on the program:
 
 ```ruby
 # Prepare transaction without sending
@@ -308,54 +212,6 @@ puts transaction.serialize  # Base64 transaction
 signature = connection.send_transaction(transaction.serialize)
 ```
 
-## Serialization System
-
-Solace uses a serialization system for converting Ruby objects to/from Solana's binary format.
-
-### SerializableRecord Base Class
-
-```ruby
-class Transaction < Solace::SerializableRecord
-  SERIALIZER = Solace::Serializers::TransactionSerializer
-  DESERIALIZER = Solace::Serializers::TransactionDeserializer
-  
-  # Automatic serialization
-  def serialize
-    self.class::SERIALIZER.call(self)
-  end
-  
-  # Automatic deserialization
-  def self.deserialize(io)
-    self::DESERIALIZER.call(io)
-  end
-end
-```
-
-### Serializer Pattern
-
-```ruby
-class TransactionSerializer < Solace::Serializers::Base
-  STEPS = %i[
-    serialize_signatures
-    serialize_message
-  ].freeze
-  
-  def serialize_signatures
-    # Convert signatures to binary format
-  end
-  
-  def serialize_message
-    # Serialize message component
-  end
-end
-```
-
-**Key Features:**
-- Step-based serialization process
-- Automatic Base64 encoding
-- Consistent error handling
-- Reversible serialization/deserialization
-
 ## Utility Modules
 
 ### Codecs
@@ -387,9 +243,6 @@ seeds = ['metadata', mint_address, 'edition']
 program_id = 'metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s'
 
 address, bump = Solace::Utils::PDA.find_program_address(seeds, program_id)
-
-# Create PDA directly
-address = Solace::Utils::PDA.create_program_address(seeds + [bump], program_id)
 ```
 
 **Key Features:**
@@ -407,6 +260,8 @@ on_curve = Solace::Utils::Curve25519Dalek.on_curve?(32_byte_point)
 
 ## Constants
 
+**WARNING: Constants will probably get deprecated in favor of config file that developers can use to define their own constants with required values.**
+
 Common Solana program IDs are defined in `Solace::Constants`:
 
 ```ruby
@@ -417,6 +272,79 @@ Solace::Constants::SYSVAR_RENT_PROGRAM_ID               # 'SysvarRent11111111111
 Solace::Constants::MEMO_PROGRAM_ID                      # 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr'
 ```
 
+## Composers
+
+Composers are used to build transactions from multiple instructions. They handle all the low-level details of transaction assembly, such as account ordering, header calculation, and fee payer selection.
+
+```ruby
+# Initialize a transaction composer
+composer = Solace::TransactionComposer.new(connection: connection)
+
+# Add an instruction composer
+composer.add_instruction(
+  Solace::Composers::SystemProgramTransferComposer.new(
+    to: 'pubkey1',
+    from: 'pubkey2',
+    lamports: 100
+  )
+)
+
+# Add another instruction composer
+composer.add_instruction(
+  Solace::Composers::SplTokenProgramTransferCheckedComposer.new(
+    from: 'pubkey4',
+    to: 'pubkey5',
+    mint: 'pubkey6',
+    authority: 'pubkey7',
+    amount: 1_000_000,
+    decimals: 6
+  )
+)
+
+# Set the fee payer
+composer.set_fee_payer('pubkey8')
+
+# Compose the transaction
+tx = composer.compose_transaction
+
+# Sign the transaction with all required signers
+tx.sign(*any_required_signers)
+```
+
+Composers are intended to be extended by developers with custom instruction composers to interface with their own programs. Simply inherit from `Solace::Composers::Base` and implement the required methods.
+
+```ruby
+class MyProgramComposer < Solace::Composers::Base
+  # All keyword arguments are passed to the constructor and available
+  # as a `params` hash.
+  # 
+  # The setup_accounts method is called automatically by the transaction composer
+  # during compilation and should be used to add accounts to the account_context 
+  # with the appropriate access permissions. Conditional logic is fine here given 
+  # and available params to determine the access permissions.
+  def setup_accounts
+    account_context.add_writable_signer(params[:from])
+    account_context.add_writable_nonsigner(params[:to])
+    account_context.add_readonly_nonsigner(params[:program])
+  end
+
+  # The build_instruction method is called automatically by the transaction composer
+  # during compilation and should be used to build the instruction using an instruction builder.
+  # 
+  # The passed context to the build_instruction method provides the indices of all accounts
+  # that were added to the account_context in the setup_accounts method. These are accessible
+  # by the index_of method of the context using the account address as a parameter.
+  def build_instruction(context)
+    Solace::Instructions::MyProgram::MyInstruction.build(
+      data: params[:data],
+      from_index: context.index_of(params[:from]),
+      to_index: context.index_of(params[:to]),
+      program_index: context.index_of(params[:program])
+    )
+  end
+end
+```
+
 ## Practical Examples
 
 ### Complete SOL Transfer
@@ -425,12 +353,15 @@ Solace::Constants::MEMO_PROGRAM_ID                      # 'MemoSq4gqABAXKb96qnH8
 require 'solace'
 
 # Setup
-connection = Solace::Connection.new('https://api.devnet.solana.com')
 payer = Solace::Keypair.generate
 recipient = Solace::Keypair.generate
 
+# Create connection
+connection = Solace::Connection.new('https://api.devnet.solana.com')
+
 # Fund payer (devnet only)
-connection.request_airdrop(payer.address, 1_000_000_000)
+response = connection.request_airdrop(payer.address, 1_000_000_000)
+connection.wait_for_confirmed_signature('finalized') { response['result'] }
 
 # Build transfer instruction
 transfer_ix = Solace::Instructions::SystemProgram::TransferInstruction.build(
@@ -455,9 +386,9 @@ message = Solace::Message.new(
 # Sign and send
 transaction = Solace::Transaction.new(message: message)
 transaction.sign(payer)
-signature = connection.send_transaction(transaction.serialize)
 
-puts "Transaction: #{signature}"
+response = connection.send_transaction(transaction.serialize)
+puts "Transaction: #{response['result']}"
 ```
 
 ### Complete Token Mint Creation
@@ -466,16 +397,19 @@ puts "Transaction: #{signature}"
 require 'solace'
 
 # Setup
-connection = Solace::Connection.new('https://api.devnet.solana.com')
 payer = Solace::Keypair.generate
 mint_keypair = Solace::Keypair.generate
 
+# Create connection
+connection = Solace::Connection.new('https://api.devnet.solana.com')
+
 # Fund payer
-connection.request_airdrop(payer.address, 1_000_000_000)
+response = connection.request_airdrop(payer.address, 1_000_000_000)
+connection.wait_for_confirmed_signature('finalized') { response['result'] }
 
 # High-level approach
-spl_token = Solace::Programs::SplToken.new(connection: connection)
-signature = spl_token.create_mint(
+program = Solace::Programs::SplToken.new(connection: connection)
+signature = program.create_mint(
   payer: payer,
   decimals: 6,
   mint_authority: payer,
@@ -487,49 +421,6 @@ puts "Mint created: #{mint_keypair.address}"
 puts "Transaction: #{signature}"
 ```
 
-### Manual Transaction Building
-
-```ruby
-# Low-level approach for maximum control
-rent_lamports = connection.get_minimum_lamports_for_rent_exemption(82)
-
-# Build instructions
-create_account_ix = Solace::Instructions::SystemProgram::CreateAccountInstruction.build(
-  from_index: 0,
-  new_account_index: 1,
-  system_program_index: 4,
-  lamports: rent_lamports,
-  space: 82,
-  owner: Solace::Constants::TOKEN_PROGRAM_ID
-)
-
-initialize_mint_ix = Solace::Instructions::SplToken::InitializeMintInstruction.build(
-  mint_account_index: 1,
-  rent_sysvar_index: 2,
-  program_index: 3,
-  decimals: 6,
-  mint_authority: payer.address
-)
-
-# Assemble transaction
-message = Solace::Message.new(
-  accounts: [
-    payer.address,
-    mint_keypair.address,
-    Solace::Constants::SYSVAR_RENT_PROGRAM_ID,
-    Solace::Constants::TOKEN_PROGRAM_ID,
-    Solace::Constants::SYSTEM_PROGRAM_ID
-  ],
-  instructions: [create_account_ix, initialize_mint_ix],
-  recent_blockhash: connection.get_latest_blockhash,
-  header: [2, 0, 3]  # 2 signers, 0 readonly signed, 3 readonly unsigned
-)
-
-transaction = Solace::Transaction.new(message: message)
-transaction.sign(payer, mint_keypair)
-signature = connection.send_transaction(transaction.serialize)
-```
-
 ## Design Patterns
 
 ### Service Objects
@@ -539,43 +430,6 @@ Instruction builders follow the service object pattern:
 - Consistent `.build()` interface
 - Separate `.data()` methods for instruction data
 
-### Serializable Records
-Core data structures inherit from `SerializableRecord`:
-- Automatic serialization/deserialization
-- Consistent binary format handling
-- SERIALIZER/DESERIALIZER constants pattern
-
-### Mixin Modules
-Shared functionality via mixins:
-- `BinarySerializable` for serialization support
-- `PDA` for Program Derived Address operations
-- `Utils` modules for common operations
-
-### Builder Pattern
-High-level program methods use builder pattern:
-- Fluent interfaces with keyword arguments
-- Sensible defaults for optional parameters
-- Automatic transaction assembly and signing
-
-## Error Handling
-
-The SDK provides comprehensive error handling:
-
-```ruby
-begin
-  signature = connection.send_transaction(transaction.serialize)
-rescue StandardError => e
-  puts "Transaction failed: #{e.message}"
-end
-
-# PDA validation
-begin
-  address = Solace::Utils::PDA.create_program_address(seeds, program_id)
-rescue Solace::Utils::PDA::InvalidPDAError => e
-  puts "Invalid PDA: #{e.message}"
-end
-```
-
 ## Testing Support
 
 The SDK includes comprehensive test utilities:
@@ -597,6 +451,7 @@ connection.wait_for_confirmed_signature { response['result'] }
 ## Dependencies
 
 - **base58**: Base58 encoding/decoding
+- **base64**: Base64 encoding/decoding
 - **rbnacl**: Ed25519 cryptography
 - **ffi**: Foreign Function Interface for native libraries
 - **json**: JSON parsing for RPC