quickstart-ruby.md

Ruby Quickstart

A comprehensive guide to using the Autonomi network with the Ruby SDK.

Setup

# Install the gem
gem install antd

# Or add to your Gemfile
# gem 'antd'

# Start local testnet
ant dev start

Connecting

require 'antd'

# REST transport (default)
client = Antd::Client.new

# Custom endpoint
client = Antd::Client.new(transport: :rest, base_url: "http://localhost:8082")

# gRPC transport
client = Antd::Client.new(transport: :grpc, target: "localhost:50051")

Health Check

status = client.health
puts "Healthy: #{status.ok}"
puts "Network: #{status.network}"  # "local", "default", or "alpha"

Public Data

Store and retrieve arbitrary bytes on the network.

# Store
result = client.data_put_public("Hello, Autonomi!")
puts "Address: #{result.address}"
puts "Cost: #{result.cost} atto tokens"

# Retrieve
data = client.data_get_public(result.address)
puts data  # "Hello, Autonomi!"

# Cost estimation — returns UploadCostEstimate with size, chunks, gas, payment mode
est = client.data_cost("some data")
puts "Estimate: #{est.file_size} bytes in #{est.chunk_count} chunks, #{est.cost} atto, gas #{est.estimated_gas_cost_wei} wei, mode #{est.payment_mode}"

Private Data

Encrypted data -- only accessible with the data map.

# Store (self-encrypting)
result = client.data_put("secret message")
data_map = result.data_map  # Keep this secret!

# Retrieve (decrypt)
data = client.data_get(data_map)
puts data

Files

# Upload a file
result = client.file_put_public("/path/to/file.txt")
puts "File address: #{result.address}"

# Download a file
client.file_get_public(result.address, "/path/to/output.txt")

# Cost estimation — returns UploadCostEstimate with size, chunks, gas, payment mode
est = client.file_cost("/path/to/file.txt")

Pointers

A pointer is an owner-signed address you can move to new data. antd signs with the owner keys it loaded at startup (antd --pointer-keys <file-or-dir>, key files from ant pointer keygen), so owner is the pointer's address, never a key. Every create, update and transfer pays (about the price of one chunk) and is never retried; reads are free. A transfer hands the pointer over to another pointer for good. Needs antd 0.16.0 or later (the first release with pointers). Walk-through: Tutorial: Point at a Public File and Update It.

owner = client.pointer_keys.first                  # a pointer antd can write

v1 = client.data_put_public("version 1").address
v2 = client.data_put_public("version 2").address

client.pointer_create(owner, v1)                   # pays; counter 0
client.pointer_update(owner, v2)                   # pays again; counter 1
target = client.pointer_resolve(owner).target      # == v2 (free)

puts client.pointer_finality(owner).status         # "open"

Counters are Integers. pointer_transfer, pointer_get, pointer_controller, pointer_prepare and pointer_finalize complete the set, on Antd::GrpcClient too.

Runnable example: antd-ruby/examples/08_pointers.rb. Set ANTD_POINTER_OWNER to an address the daemon holds a key for, one it has not written yet (each run creates the pointer and pays for its writes), and ANTD_BASE_URL for a daemon other than http://localhost:8082:

ANTD_POINTER_OWNER=<address> ruby antd-ruby/examples/08_pointers.rb

Error Handling

The Ruby SDK raises exceptions on errors.

begin
  client.data_get_public("nonexistent")
rescue Antd::NotFoundError
  puts "Not found"
rescue Antd::PaymentError
  puts "Payment issue"
rescue Antd::NetworkError
  puts "Network unreachable"
rescue Antd::AntdError => e
  puts "Error (#{e.status_code}): #{e.message}"
end

Exception hierarchy:

Exception	HTTP Code	When
Antd::BadRequestError	400	Invalid parameters
Antd::PaymentError	402	Insufficient funds
Antd::NotFoundError	404	Resource not found
Antd::AlreadyExistsError	409	Duplicate creation
Antd::ForkError	409	Version conflict
Antd::TooLargeError	413	Payload too large
Antd::InternalError	500	Server error
Antd::NetworkError	502	Network unreachable

Manifests

A manifest describes a set of files as one ant://manifest/ link, or as a .ant file when the link would be too long. Each entry is either a public file's address or an embedded DataMap (the manifest is then the key to a private file), with an optional path. Building and decoding upload and pay for nothing: upload the files first, then describe them. Needs antd 0.16.0 or later. Walk-through: Tutorial: Share a Set of Files as One Link.

a = client.data_put_public("one").address        # pays
b = client.data_put_public("two").address        # pays

built = client.build_manifest(                   # free
  [{ path: "notes/one.txt", address: a }, { path: "notes/two.txt", address: b }],
  name: "example"
)
puts built.link                                  # nil when over 1,500 bytes: share built.manifest instead

client.decode_manifest_link(built.link, resolve: true).entries.each do |e|   # free
  puts "#{e.effective_name}: #{e.exact_size} bytes"
end

decode_manifest(bytes, resolve: true) takes raw .ant bytes. Entries may also be Antd::ManifestEntryInputs; use data_map: instead of address: for an embedded entry, and embed_roots: false to keep shrunk DataMaps as given. On Antd::GrpcClient too.

Every upload result (DataPutResult, DataPutPublicResult, FilePutResult, FilePutPublicResult and, for external-signer uploads, FinalizeUploadResult) also has sha256 (nil when none): the plaintext's SHA-256 (hex). To record it in a manifest, pass it as the entry's sha256: Antd::ManifestEntryInput (or a Hash entry) takes sha256:, and entries read it back as sha256. Requires antd 0.17.0 or later; the SDK sends it only when set and does not check it.

Runnable example: antd-ruby/examples/09_manifests.rb. Its two uploads pay; the manifest calls do not.

ANTD_BASE_URL=http://localhost:8082 ruby antd-ruby/examples/09_manifests.rb

Examples

# Run individual examples
ant dev example connect -l ruby
ant dev example data -l ruby
ant dev example all -l ruby

# Or directly
ruby antd-ruby/examples/01_connect.rb
ruby antd-ruby/examples/02_data.rb

See antd-ruby/examples/ for the complete set of examples.