Ruby SDK

Full API reference for truthid-sdk on RubyGems. New to TruthID? Start with the Quickstart — this page is the detailed reference for every method and type once you're integrating for real.

Installation

gem install truthid-sdk

Requires Ruby 3.0+.

TruthID::Client

require "truthid"

truthid = TruthID::Client.new  # defaults to network: "base-mainnet"

There's also a factory function, if you prefer it:

truthid = TruthID.new_client  # equivalent to TruthID::Client.new

Constructor

TruthID::Client.new(network: "base-mainnet", rpc_url: nil)

Like Python, network has a default here — you only need to pass it to override or to use the testnet. (The TypeScript SDK requires it explicitly, with no default.)

Methods

create_challenge(origin)

Creates a one-time challenge to embed in the QR code shown to the user.

Parameters

Returns AuthChallenge

challenge = truthid.create_challenge("yoursite.com")
challenge.nonce      #=> "3f2e1a4b-..."
challenge.issued_at  #=> 1718000000000

Building the QR code — the mobile app expects this exact shape (challenge.to_h already produces the right camelCase keys):

{
  "action": "truthid-auth",
  "challenge": { "type": "challenge", "nonce": "...", "issuedAt": 1718000000000, "origin": "yoursite.com" },
  "callbackUrl": "https://yoursite.com/auth/verify"
}

callbackUrl must use https:// — the mobile app refuses to send the signed response to a plain http:// URL.

verify_auth_response(challenge, response, ttl_ms: 30_000)

Verifies the signed response received from the user's phone. Runs six checks in sequence and stops at the first failure:

1. User approved (not rejected)
2. Challenge is within TTL (default: 30 seconds)
3. Nonce matches the original challenge
4. Cryptographic signature is valid
5. Device is registered and active on the blockchain
6. Retrieves the identity ID linked to this device

Parameters

Returns VerifyAuthResult

AuthResponse.from_hash builds it straight from the parsed JSON body — unlike the Python SDK, no manual field mapping needed:

data = JSON.parse(request.body.read)  # { "approved" => ..., "nonce" => ..., "signature" => ..., "deviceAddress" => ... }

response = TruthID::AuthResponse.from_hash(data)
result = truthid.verify_auth_response(challenge, response)

if result.valid
  puts "Authenticated! Identity ID: #{result.identity_id}"
else
  puts "Failed: #{result.reason}"
end

Failure reasons

verify_session(session_hash)

Checks whether a session hash is still valid (not revoked). Call this on subsequent requests after login to confirm the session hasn't been revoked from another device.

Parameters

Returns SessionInfo

session = truthid.verify_session(session_hash)
if session.exists && !session.revoked
  # still logged in
end

check_device_status(device_pub_key)

Looks up a device's current status on the blockchain.

Parameters

Returns DeviceStatus

status = truthid.check_device_status(device_pub_key)

compute_smart_account_address(ledger_address, index: 0)

Predicts a user's smart account (controller) address via CREATE2 — pure local computation, no RPC call and no server involved. Useful for showing a deposit address, or checking a balance, before the account has ever been used on-chain.

Parameters

Returns String — the checksummed smart account address.

smart_account = truthid.compute_smart_account_address(ledger_address)

A module-level function is also available for when you don't need a full client instance:

smart_account = TruthID.compute_smart_account_address(ledger_address, network: "base-mainnet")

Types

All of the following are in the TruthID module. AuthChallenge and AuthResponse are plain classes — their attributes follow normal Ruby snake_case (issued_at, device_address), and each has a conversion method (to_h / from_hash) at the boundary where it meets the camelCase JSON the mobile app actually sends and signs. VerifyAuthResult, SessionInfo, and DeviceStatus are Structs, since they never cross the wire.

AuthChallenge

class AuthChallenge
  attr_reader :type, :nonce, :issued_at, :origin

  # to_h => { "type" => ..., "nonce" => ..., "issuedAt" => ..., "origin" => ... }
end

AuthResponse

class AuthResponse
  attr_reader :approved, :nonce, :signature, :device_address, :session_signature

  # self.from_hash(h) reads h["deviceAddress"] into device_address, etc.
  # session_signature: personal_sign over keccak256(nonce) — always sent alongside signature
end

VerifyAuthResult

VerifyAuthResult = Struct.new(:valid, :identity_id, :device_address, :reason, keyword_init: true)

SessionInfo

SessionInfo = Struct.new(:exists, :revoked, :identity_id, :device_pub_key, :created_at, keyword_init: true)

DeviceStatus

DeviceStatus = Struct.new(:exists, :active, :label, :identity_id, :added_at, keyword_init: true)

Security notes

Nonce invalidation

Delete the challenge from your store before calling verify_auth_response, not after — deleting after leaves a race condition where the same signed response can be submitted twice within the TTL window.

# Correct order
pending_challenges.delete(response.nonce)            # delete first
result = truthid.verify_auth_response(challenge, response)  # then verify

TTL

The default is 30 seconds, matching the mobile app's own challenge expiry. Lowering it is fine; raising it above 30 seconds has no effect, since the phone will already refuse an older challenge.

HTTPS only

The phone POSTs the signed response directly to your callback URL — the mobile app refuses non-https:// URLs, and your endpoint still needs a valid TLS certificate for the connection to succeed.

Networks

# Testnet during development
truthid = TruthID::Client.new(network: "base-sepolia")

# Custom RPC instead of the public endpoint
truthid = TruthID::Client.new(network: "base-mainnet", rpc_url: "https://your-private-rpc.example.com")

Contract addresses for both networks are in Smart contracts.

Session visibility — nothing to do

Completed logins already show up in the user's TruthID mobile/desktop apps and can be individually revoked from there. The phone registers the session on-chain itself (via a UserOperation) before it ever calls your callback URL — there's no separate registration step for you to call.

If you want to double-check a session landed on-chain, derive its hash from the nonce and call verify_session:

session_hash = "0x" + Eth::Util.keccak256(response.nonce).unpack1("H*")
session = truthid.verify_session(session_hash)
if session.exists && !session.revoked
  # confirmed on-chain
end

Next steps

• Quickstart — full walkthrough from install to first login
• Full Sinatra example with session tokens and a protected route
• TypeScript SDK reference
• Python SDK reference