Skip to main content
Version: 2.0.4

Sessions

Sessions play a vital role in enabling secure, trustless atomic swaps while also delivering a seamless swapping experience. For integrators, sessions provide a unified framework to manage secrets, interact with Bitcoin’s P2SH addresses, and ensure smooth interactions without compromising security. By abstracting complex processes like secret generation and Bitcoin wallet integration, sessions simplify the developer experience while maintaining robust protections for users.

Why do we need sessions?​

In traditional apps, users authenticate once and perform multiple actions seamlessly. dApps, on the other hand, often require repeated prompts for signing and confirmations, which can create unnecessary friction. We developed an app session architecture to eliminate these inefficiencies while maintaining the decentralized and trustless nature of atomic swaps.

How do sessions work?​

Secure key generation and storage​

Sessions begin with the creation of a P-256 key, derived securely from the user’s EIP-712 signature. This key is unique to the user and serves as the foundation for managing secrets and interactions. It is securely stored in the browser’s IndexedDB, ensuring persistence across sessions without exposing the key to tampering or misuse.

Bitcoin wallet integration​

Atomic swaps on the Bitcoin network require funds to be locked and redeemed from P2SH (Pay-to-Script-Hash) addresses, which most Bitcoin wallets do not natively support. Garden’s sessions leverage the P-256 key as a lightweight Bitcoin wallet. This enables users to unlock P2SH addresses, redeem funds securely, and direct them to their desired Bitcoin addresses without needing specialized wallet functionality.

Secrets management​

The session securely generates and manages the cryptographic secrets required for atomic swaps. Using the P-256 key, Garden derives the secret and secret hash for each transaction:

  • The secret is the hash of the EIP-712 signature.
  • The secret hash is the double hash of the signature.

This ensures the integrity of the swap process while maintaining trustlessness.

Workflow​

Session components come together to power atomic swaps seamlessly:

  • Session initialization: The P-256 key acts as a secure anchor for all subsequent interactions, ensuring user-specific, cryptographically protected actions.
  • Quote and intent creation: The session securely handles signing and broadcasting the user's intent to swap assets, ensuring no custody risk and aligning with atomic swap requirements.
  • Script management: The secrets and script hashes generated by the session enable conditional fund transfers using P2SH addresses, maintaining trustlessness in the swap process.
  • Redemption and settlement: The session manages the interaction with the destination chain, unlocking funds securely and ensuring seamless coordination between the user and solver.

How sessions improve security​

Sessions ensure users retain full control of their assets throughout the swap process. The P-256 key is generated dynamically for each user and tied directly to their session, preventing unauthorized access. By storing the key in IndexedDB, it remains isolated within the browser’s same-origin policy, making it inaccessible to external threats. Additionally, secrets are generated per transaction, ensuring they are unique and valid only for the specific swap.