Calimero Network for Ruby

Calimero.rb is a Ruby client library for the Calimero Network.

[!TIP] 🚧 We are building in public. This is presently under heavy construction.

✨ Features

• Implemented natively in Ruby with minimal dependencies, ensuring low overhead and efficient performance.
• Implements a JsonRpcClient for sending queries and updates to the applications in Calimero nodes.
• Handles write and read calls to Calimero network applications.
• Handles config management of Calimero nodes.
• Manages authentication workflow using Ed25519-keypair.
• 🚧 Manages authentication workflow using token acquisitions and refresh.
• 🚧Implements a WsSubscriptionsClient for subscribing to real-time updates from the Calimero nodes.
• 🚧 Supports interaction with Calimero Admin and Calimero Node APIs.
• Adheres to the Ruby API Guidelines in its [naming conventions].
• 100% free and unencumbered public domain software.

🛠️ Prerequisites

• Ruby 3.0+

⬇️ Installation

Installation via RubyGems

gem install calimero

👉 Examples

Importing the library

require 'calimero'

Loading the Calimero config

You can load a Calimero config file the following way:

require 'calimero'

config_path = "/path/to/your/calimero/config.toml"
config = Calimero::load_config(config_path)

If you would like to utilize the default Calimero config folder:

require 'calimero'

config_path = "#{Calimero::default_config_folder}/node1/config.toml"
config = Calimero::load_config(config_path)

Importing Ed25519Keypair from the config and signing an arbitrary message with it

require 'calimero'

config_path = "#{Calimero::default_config_folder}/node1/config.toml"
config = Calimero::load_config(config_path)

message = "Hello, Calimero"
signature = config.keypair.sign(message)

Importing Ed25519Keypair from base58-encoded protobuf message and signing an arbitrary message with it

require 'calimero'

# The keypair should be base58-encoded protobuf message (using `libp2p_identity::Keypair`)
keypair_base58_protobuf = "<YOUR_BASE58_ENCODED_ED25519_KEYPAIR>"
keypair = Ed25519Keypair.new(keypair_base58_protobuf)
message = "Hello, Calimero"
signature = keypair.sign(message)

Executing arbitrary method in Calimero Application with authentication using dev JSONRPC endpoint

require 'calimero'
require 'base58'

client = JsonRpcClient.new('http://localhost:2428', '/jsonrpc/dev')
params = RpcQueryParams.new('your_application_context_id', 'some_method', { 'some': 'args' }, 'executor_public_key')

config_path = "#{Calimero::default_config_folder}/node1/config.toml"
config = Calimero::load_config(config_path)

timestamp = Time.now.utc.to_i.to_s
signature = config.keypair.sign(timestamp)
signature_b58 = Base58.binary_to_base58(signature, :bitcoin)

headers = {
  'Content-Type' => 'application/json',
  'X-Signature' => signature_b58,
  'X-Timestamp' => timestamp
}
request_config = RequestConfig.new(timeout: 1000, headers: headers)
result = client.execute(query_params, request_config)
if result.error
  puts "Error: #{result.error}"
else
  puts "Result: #{result.result}"
end

Executing arbitrary method in Calimero Application

require 'calimero'

client = JsonRpcClient.new('http://localhost:2428', '/jsonrpc')
params = RpcQueryParams.new('your_application_context_id', 'some_method', { 'some': 'args' }, 'executor_public_key')
bearer_auth_token = "some bearer auth token"
headers = {
  'Content-Type' => 'application/json',
  'Authorization' => "Bearer #{bearer_auth_token}"
}
request_config = RequestConfig.new(timeout: 1000, headers: headers)
result = client.execute(params, request_config)
if result.error
  puts "Error: #{result.error}"
else
  puts "Result: #{result.result}"
end

Fetching all posts from OnlyPeers application

You can query all the posts in the given OnlyPeers demo application, by using the following example:

CONTEXT_ID=<ONLYPEERS_CONTEXT_ID> EXECUTOR_PUBLIC_KEY=<YOUR_EXECUTOR_PUBLIC_KEY> ruby examples/onlypeers_get_all_posts.rb

That example also contains an example on how to use the Config and Ed25519Keypair to authenticate your requests to the Calimero node.

📚 Reference

https://rubydoc.info/gems/calimero

👨‍💻 Development

git clone https://github.com/dryruby/calimero.rb.git

---