Solace

A Ruby SDK for the Solana blockchain. Solace lets you build, sign, and send Solana transactions from idiomatic Ruby — from hand-assembling a message byte by byte, up to one-call program clients that derive accounts, sign, and submit for you. It ships a native Ed25519/Curve25519 extension (prebuilt for Linux, macOS, and Windows), so there's nothing to compile.

📖 Documentation: https://zarpay.github.io/solace

The gem lives in gem/; the documentation site (VitePress) lives in site/.

Quick start

require 'solace'

connection = Solace::Connection.new('https://api.devnet.solana.com')
payer      = Solace::Keypair.generate
recipient  = Solace::Keypair.generate

# Compose, sign, and send a SOL transfer.
tx = Solace::TransactionComposer.new(connection:)
                                .add_instruction(
                                  Solace::Composers::SystemProgramTransferComposer.new(
                                    from:     payer.address,
                                    to:       recipient.address,
                                    lamports: 1_000_000
                                  )
                                )
                                .set_fee_payer(payer.address)
                                .compose_transaction

tx.sign(payer)
result = connection.send_transaction(tx.serialize)
connection.wait_for_confirmed_signature { result['result'] }

See the Quick Start guide for the full walkthrough.

Four layers, pick your altitude

Solace is organized as four layers — higher layers are more convenient, lower layers give more control. Every operation is reachable at more than one level.

Layer	What it is
Program clients (`Solace::Programs::*`)	Send-and-sign clients that derive accounts, build, sign, and submit (e.g. `SplToken#create_mint`).
Composers (`Solace::Composers::*`)	Each contributes one instruction to a transaction, managing its own accounts; assembled by `TransactionComposer`.
Instruction builders (`Solace::Instructions::*`)	Stateless `.build` methods that encode a single raw instruction from account indices.
Core primitives	`Keypair`, `PublicKey`, `Connection`, `Transaction`, `Message`, `Instruction`, `AccountContext`.

What's covered

Core primitives — keypairs & public keys, the RPC connection, transactions and messages (legacy and versioned), instructions, account context, and address lookup tables.
Building transactions — instruction builders, composers, the transaction composer, and program clients.
Programs — the System program, SPL Token, Token-2022, and the Associated Token Account program.
Reference — codecs, PDA derivation, Curve25519, constants, serialization, tokens, and errors.

Full documentation per topic lives on the docs site.

Install

# Gemfile
gem 'solace'

bundle install

Native binaries for the Curve25519 operations ship with the gem for Linux, macOS, and Windows (x86_64 and ARM64).

Development

The gem lives in gem/; run all gem commands from there:

cd gem
bundle install
bundle exec rake bootstrap   # start a solana-test-validator and fund the fixture accounts
bundle exec rake test        # run the test suite against the funded validator
bundle exec rubocop          # lint

Tests run against a local solana-test-validator. Run rake bootstrap once to fund the fixture keypairs (the funded ledger persists in test-ledger/), then rake test.

The native Rust extension is prebuilt and committed under gem/lib/solace/utils/; rebuild it with rake compile (needs a Rust toolchain) or the build-libs GitHub Actions workflow.

The documentation site is a VitePress app in site/:

cd site
npm install
npm run dev     # local preview
npm run build   # static build

License

Released under the MIT License.

solace

Development

Runtime

Solace

Quick start

Four layers, pick your altitude

What's covered

Install

Development

License