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.
The P-256 key is generated using cryptographically secure methods and is tied directly to the user’s wallet signature, ensuring each session is unique and secure.

​
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:
  1. Session initialization: The P-256 key acts as a secure anchor for all subsequent interactions, ensuring user-specific, cryptographically protected actions
  2. 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
  3. Script management: The secrets and script hashes generated by the session enable conditional fund transfers using P2SH addresses, maintaining trustlessness in the swap process
  4. 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.
Key security benefits include:
  • User control: Users retain full ownership of their assets throughout the entire swap process
  • Unique secrets: Secrets are generated per transaction, ensuring they are unique and valid only for the specific swap
  • Browser isolation: Keys are stored securely in IndexedDB with same-origin policy protection
  • No custody risk: Garden never holds user funds or private keys
  • Cryptographic integrity: All operations use proven cryptographic methods for maximum security

​
Integration considerations

When integrating sessions into your application:
  • Sessions handle complex Bitcoin operations automatically
  • No need to implement P2SH address management
  • Secrets are managed securely without developer intervention
  • Session persistence across browser refreshes
  • Automatic cleanup of expired sessions

​
Next steps

Order lifecycle

Understand how orders progress through different states

SDK integration

Learn how to integrate Garden SDK with session support