Kalyx / technical field guide
Developer quickstart
Start with a free probe. Do not run paid retrieval against a deployed gateway until its canonical DEVNET program, matching IDL, and signer workflow are published and independently verified.
Install the SDK candidate
The SDK is distributed from the tagged Git repository, not PyPI.
Python 3.10 or later is required. Keep a DEVNET-only keypair outside browser code and source control. The SDK is designed to refuse mainnet and an unidentifiable or mismatched cluster.
pip install "git+https://github.com/DakshSinghDhami/kalyx-sdk.git@v0.1.3"Probe without payment
A probe is the supported starting point because it never signs or funds a transaction.
The candidate contract defines POST /v1/query as either a 200 no_context_found response or a 402 challenge. A challenge is a quote, not a charge. Never treat an empty node address as payable.
from kalyx_sdk import KalyxClient
client = KalyxClient()
probe = client.probe("how are KALYX escrows settled?")
if probe.challenge is None:
print("no relevant context (free)")
else:
print("quoted lamports:", probe.challenge.price_lamports)Paid retrieval is deliberately gated
The SDK has a query_and_retrieve API, but the current public integration must not be presented as a funded DEVNET quickstart.
This gate exists because the currently inspected DEVNET program and candidate source/IDL have incompatible identities and account layouts. No browser page should request a private key, operator bearer token, or seed phrase.
- Read /v1/config and verify the intended cluster and program against a designated trusted IDL.
- Verify the challenge binds the expected node, publisher, content hash, and price.
- Set an explicit per-call cap and session budget before signing.
- Confirm the funding signature before POST /v1/retrieve; hash-check returned content.
- Treat settlement as pending until independently confirmed settlement evidence exists.
Persistence and recovery contract
A paid answer is expected to be bound to one funding signature, escrow address, and chunk identifier.
The candidate backend documents replay-safe retrieval of the same binding after restart, while reuse of a payment identifier for a different binding is rejected. Retry 429 or 503 responses only as instructed; after an ambiguous payment broadcast, reconcile rather than rebroadcast.
THE JUDGE PATH / FOLLOW THE CONTEXT
From the idea to the evidence.
The demo uses real devnet transactions. Content integrity and a receipt signature do not establish payout. Live availability and blocked steps are shown explicitly.