Sundial

We express our gratitude to the Sundial team for the collaborative engagement that enabled the execution of this dApp Security Assessment.

Sundial Protocol is building Bitcoin-native yield infrastructure, enabling users to lock BTC into time-based escrow contracts and earn yield through a decentralized staking mechanism. The protocol leverages Bitcoin Script primitives (CLTV, CSV) to create trustless timelock and escrow outputs, allowing for non-custodial yield distribution without requiring wrapped tokens or cross-chain bridges.

The system users should acknowledge all the risks summed up in the risks section of the report

{FindingsVulnSeverityStatusTable}

Documentation quality

• Comprehensive top-level README.md with protocol overview, installation instructions, and usage examples

• Detailed CLI.md documenting all command-line operations with flags and examples

Code quality

• Strong TypeScript usage with strict typings, dedicated types.ts, and interface definitions for all transaction parameters

• Clean modular architecture with single-responsibility separation (locker/scripts/, locker/transactions/, utils/)

The BTC Locker core library lives in its own top-level /packages/core folder and is responsible for Bitcoin script generation, PSBT construction, transaction signing, and on-chain interaction with Bitcoin APIs. Inside there is:

A README.md and supporting documentation that explain overall setup, usage patterns, and integration guidance for the Sundial staking workflow.

src/ with several subdirectories and standalone modules:

• locker/ — the primary module containing Bitcoin locking primitives:

• • core.ts which provides the BTCLockerCore base class handling ECC initialization, transaction signing, and PSBT finalization logic.

  • index.ts exposing the unified BTCLocker facade class that combines key generation, script management, and transaction building into a single interface.

  • keypair.ts for Bitcoin key pair generation (random and from existing private keys) using the secp256k1 curve.

  • script-manager.ts and transaction-manager.ts as thin facades delegating to specialized builders.

  • scripts/ subdirectory containing:

  • • timelock.ts for absolute (CLTV) and relative (CSV) timelock script creation.

    • escrow.ts for dual-path escrow scripts with before/after deadline spending conditions.

  • transactions/ subdirectory containing:

  • • deposit/ with deposit.ts, deposit-with-script.ts, and calculate.ts for Dawn Protocol staking transactions that split funds between escrow and timelock outputs.

    • withdraw.ts for combining escrow and timelock inputs into a single withdrawal transaction.

    • claim.ts for spending from escrow scripts using either the before-deadline or after-deadline path.

    • distribute.ts for yield distribution transactions back to timelock addresses.

    • generic.ts providing low-level spending and funding transaction primitives.

• utils/ — shared utility modules:

• • scripts.ts with helpers for script validation, address generation, script parsing, and locktime extraction.

  • keys.ts for public/private key validation and ECPair creation.

  • fees.ts encapsulating fee estimation logic with priority levels (HIGH/MEDIUM/LOW) and dust threshold calculations.

  • transactions.ts for UTXO selection, witness input construction, and metadata output appending.

  • metadata.ts implementing the Sundial OP_RETURN metadata protocol (60-byte schema with magic bytes, version, transaction type, deposit ID, provider pubkey, flags, and CRC-32 checksum).

  • validation.ts with common parameter validation (locktime, amounts, protocol fees).

  • time.ts for timestamp/date conversions and duration calculations.

  • network.ts defining Bitcoin network configurations (mainnet, testnet, regtest).

• bitcoin-api.ts — integration layer for external Bitcoin APIs (Mempool.space, Blockstream, BlockCypher) providing UTXO fetching, transaction broadcasting, fee estimation, and block height queries.

• errors.ts defining custom error classes (BTCLockerError, ValidationError, TimelockError) for structured error handling.

• types.ts and index.ts for TypeScript type definitions and public API exports.

Supporting files include package.json, TypeScript configurations (tsconfig.json, tsconfig.build.json), Vitest test suite under tests/, ESLint/Prettier configs, and webpack bundling configuration for browser distribution.

The scope of the project includes the following: