Telegram Bot
The Atomic Swap Telegram bot functions as a coordination mechanism that bridges human-negotiated OTC agreements with protocol-enforced atomic settlement. It does not participate in cryptographic enforcement or execution authority. Instead, it orchestrates information flow and user actions in a way that aligns informal negotiation with the strict requirements of HTLC-based atomic swaps.
At a mechanical level, the bot operates as a finite-state coordinator that observes public blockchain state, collects user-declared intent, and emits action prompts. It never controls assets, secrets, or transaction execution.
Separation of Responsibilities
The overall atomic swap system is partitioned into three responsibility domains:
Human negotiation and agreement
Coordination and state interpretation
Cryptographic enforcement and settlement
The Telegram bot occupies the second domain exclusively. Human participants negotiate trade terms directly through Telegram. Cryptographic enforcement occurs entirely on-chain via HTLCs. The bot exists between these layers to translate agreement into executable structure and to track execution progress.
This separation ensures that compromise or failure of the bot cannot affect settlement correctness.
Trade Intent Capture and Normalization
The first mechanical function of the bot is to capture trade intent after counterparties reach agreement.
OTC negotiation produces informal descriptions of a trade, typically expressed in natural language. These descriptions are ambiguous and unsuitable for direct execution. The bot prompts users to explicitly declare:
participant addresses
asset identifiers and quantities
chains involved
expected settlement order
timelock parameters
The bot then normalizes this information into a canonical trade intent object. This object is a structured data representation that maps directly to atomic swap parameters. It does not encode pricing logic, validation rules, or asset semantics. Its sole purpose is to remove ambiguity before execution.
Once normalized, the trade intent is immutable for the duration of the swap.
Atomic Swap Initialization Sequence
After intent normalization, the bot guides users through the atomic swap initialization sequence.
Mechanically, this sequence proceeds as follows:
One party generates a cryptographic secret locally.
The hash of the secret is shared with the counterparty and registered in the trade intent.
The bot determines the correct timelock ordering based on chain characteristics.
The bot prompts the initiating party to deploy the first HTLC.
The bot waits for on-chain confirmation before advancing state.
The bot does not generate secrets, store secrets, or verify cryptographic correctness. It only ensures that prerequisites are satisfied before prompting the next action.
HTLC Deployment Coordination
HTLC deployment occurs independently on each chain involved in the swap.
The bot tracks deployment by observing public blockchain state. Once an HTLC is confirmed on-chain, the bot updates the trade state and notifies the relevant participants.
If an HTLC is deployed incorrectly or with mismatched parameters, the bot does not attempt to correct or override execution. It simply flags the discrepancy and halts progression. Resolution in such cases is manual and does not endanger funds.
Redemption and Secret Propagation
Settlement is triggered when one party redeems an HTLC by revealing the secret on-chain.
The bot continuously monitors for redemption events associated with the trade’s hash commitment. When a redemption is detected:
the bot extracts the now-public secret from chain data
the bot notifies counterparties that redemption conditions are satisfied
the bot advances the trade state to redemption-ready for remaining HTLCs
The bot does not relay the secret off-chain in a privileged manner. It only points participants to publicly observable data. Users remain responsible for executing redemption transactions through their own wallets.
Refund Detection and Timeout Handling
If settlement does not complete within the allocated time window, the bot transitions the trade state to refund-eligible.
Mechanically, this occurs when the bot detects that a timelock has expired on any HTLC. At this point:
the bot notifies affected parties
the bot provides guidance on refund execution
the trade state is marked as terminal
Refund execution does not require bot approval. Users can initiate refunds directly on-chain regardless of bot availability.
State Tracking and Consistency Model
The bot maintains an internal state machine that mirrors, but does not replace, the on-chain state of HTLCs.
Typical states include:
intent finalized
first HTLC deployed
counter HTLC deployed
redemption observed
refund eligible
trade resolved
State transitions are driven exclusively by observable blockchain events and explicit user input. The bot does not infer hidden state or rely on off-chain promises.
In the event of inconsistency between bot state and on-chain state, on-chain data always takes precedence.
Failure Modes and Safety Properties
The mechanism explicitly assumes that the bot may fail at any point.
If the bot becomes unavailable:
users can continue interacting with HTLC contracts directly
secrets can still be revealed on-chain
refunds remain accessible after expiration
If the bot provides incorrect guidance:
no automatic execution occurs
users must independently verify parameters before signing transactions
No execution path exists in which bot malfunction can cause asset loss.
Why the Bot Is Necessary Despite Being Non-Critical
While the atomic swap protocol is usable without the bot, practical OTC trading across chains involves coordination complexity that scales poorly without assistance.
The bot reduces:
human error in parameter coordination
missed timelock windows
confusion around execution order
cognitive overhead in cross-chain swaps
This improves execution reliability without altering the underlying trust model.
Summary
The Atomic Swap Telegram bot operates as a coordination state machine layered on top of cryptographic settlement primitives. It captures informal agreement, normalizes execution parameters, tracks on-chain state, and guides users through required actions.
It does not custody assets, handle secrets, or enforce outcomes. All guarantees remain enforced by HTLCs and underlying blockchains. The bot improves usability and coordination while remaining fully optional and non-authoritative.
Last updated