Bitty-City

This project prescribes the custodial product experience for bitcoin on-chain operations. It is used currently by Block for Square Bitcoin withdrawals.

Building

Bitty City uses CashApp's Hermit. Hermit ensures that your team, your contributors, and your CI have the same consistent tooling. Here are the installation instructions.

Activate Hermit either by enabling the shell hooks (one-time only, recommended) or manually sourcing the env with . ./bin/activate-hermit.

Use gradle to run all tests:

bin/gradle build

Project Structure

• outie/ - Withdrawals module
• outie-jooq-provider - jOOQ bindings for the outie module
• innie/ - Deposits module (WIP)

Modules

Innie

Handles bitcoin deposit operations and related custodial product experience.

Outie

Handles bitcoin withdrawal operations and related custodial product experience. See the state machine diagram for details on the withdrawal flow.

Outie-jOOQ-Provider

jOOQ bindings for the outie module.

Database Migrations

This module uses Flyway for database migrations. Migrations are located in the outie-jooq-provider/src/main/resources/migrations directory.

Migration File Naming Convention

Migration files must follow the Flyway naming convention:

• Format: V{version}__{description}.sql
• Example: V20250414.1414__create_withdrawals_table.sql
• The version must start with an uppercase 'V'
• Use periods (not underscores) in the version number
• Double underscores between version and description
• Description uses underscores for spaces