Skip to content

readme.md

Latest commit

 

History

History
270 lines (215 loc) · 14 KB

readme.md

File metadata and controls

270 lines (215 loc) · 14 KB

Daedalus Agent Documentation Index

For AI Agents: Read this file first to understand available documentation and when to reference each resource.

This folder contains all the documentation needed for AI agents to effectively assist with development on the Daedalus project. Use this index to quickly navigate to the relevant documentation for your current task.

Quick Navigation

Folder Purpose When to Read
/system Architecture, APIs, state management First, for any architectural decisions or understanding system design
/plans PRDs and implementation plans history When implementing new features similar to past work
/SOPs Standard Operating Procedures When encountering known issues or following established patterns
/skills Reusable task-specific playbooks When making domain-specific changes (CLI, frontend, testing)
/workflows Step-by-step development workflows When executing specific development tasks

Folder Details

/system — Architecture & APIs

The source of truth for major architectural decisions.

Read these files to understand:

  • Electron main/renderer process architecture
  • IPC communication patterns
  • MobX state management
  • cardano-wallet REST API integration

Files:

  • architecture.md — System overview, Electron architecture, IPC patterns, data flow
  • api-endpoints.md — cardano-wallet REST API, IPC channels
  • state-management.md — MobX store architecture and patterns

/plans — Implementation History

Successful PRDs and implementation plans for reference.

Before implementing a feature:

  1. Check if a similar feature was implemented before
  2. Use past plans as templates for consistency
  3. Follow established patterns from successful implementations

This folder uses subdirectories per major feature/task. Subdirectories may also include companion design specs and research notes when a task needed deeper implementation detail or source-of-truth investigation.

/SOPs — Standard Operating Procedures

Learnings from resolved issues and best practices.

When an issue is resolved or a complex integration succeeds:

  1. Document the step-by-step solution
  2. Include common pitfalls and how to avoid them
  3. Reference related code or configuration

To create a new SOP, ask the agent:

"Generate SOP for [task/integration name]"

/skills — Reusable Skills

Reusable, task-specific playbooks organized by domain.

Cardano CLI

Skill Description
bech32-encoding-decoding Encode/decode bech32 strings
cardano-cli-doctor Diagnose cardano-cli versions and flags
cardano-cli-plutus-scripts Plutus script guidance
cardano-cli-plutus-scripts-operator Plutus script execution (operator)
cardano-cli-staking Staking operations guidance
cardano-cli-staking-operator Staking execution (operator)
cardano-cli-transactions Transaction building guidance
cardano-cli-transactions-operator Transaction execution (operator)
cardano-cli-wallets Wallet operations guidance
cardano-cli-wallets-operator Wallet execution (operator)
cardano-protocol-params Protocol parameters diagnostics
cbor-encoding-decoding CBOR encoding/decoding guidance

Frontend

Skill Description
i18n-messaging Manage react-intl i18n messaging
theme-management CSS variables theme system
storybook-creation Create/update Storybook stories

General

Skill Description
e2e-test-creation Create Cucumber BDD e2e tests
git-commit-formatter Conventional commit formatting

/workflows — Development Workflows

Step-by-step guides for common development tasks.

Available workflows:

Workflow Description Trigger
build.md Nix shells and Yarn builds /build
test.md Jest and Cucumber testing /test
electron.md Electron main process development /electron
frontend.md React/MobX development /frontend
hardware-wallets.md Ledger/Trezor development /hardware-wallets
ipc.md IPC channel development /ipc
nix.md Nix environment setup /nix
storybook.md Storybook component work /storybook
update-doc.md Update documentation /update-doc

Project Overview

Daedalus is the official full-node cryptocurrency wallet for Cardano, built with Electron. It runs a full cardano-node and cardano-wallet backend, providing maximum security and decentralization.

Architecture Overview

+-----------------------------------------------------------------------------+
|                          DAEDALUS WALLET (Electron)                         |
+-----------------------------------------------------------------------------+
|                                                                             |
|  +-------------------------------+    +-----------------------------------+ |
|  |      Renderer Process         |    |          Main Process             | |
|  |      (React/MobX UI)          |    |      (Node.js/Electron)           | |
|  +-------------------------------+    +-----------------------------------+ |
|  | source/renderer/app/          |    | source/main/                      | |
|  | +-- components/ (React)       |    | +-- cardano/                      | |
|  | +-- stores/ (MobX)            |    | |   +-- CardanoNode.ts            | |
|  | +-- api/ (HTTP client)        |    | |   +-- CardanoWalletLauncher.ts  | |
|  | +-- containers/               |    | |   +-- setup.ts                  | |
|  | +-- themes/                   |    | +-- ipc/ (IPC handlers)           | |
|  | +-- i18n/                     |    | +-- menus/ (native menus)         | |
|  +--------------+----------------+    | +-- trezor/ (Trezor Connect)      | |
|                 |                     | +-- windows/ (window mgmt)        | |
|                 |                     | +-- utils/ (logging, etc)         | |
|                 |                     +----------------+------------------+ |
|                 |                                      |                    |
|                 |         Electron IPC                |                     |
|                 +----------------+--------------------+                     |
|                                  |                                          |
+----------------------------------+------------------------------------------+
|                      REST API (localhost:8090)                              |
|                                  |                                          |
|  +-------------------------------+--------------------------------------+   |
|  |                        cardano-wallet (Haskell)                      |   |
|  |                    External process managed by Daedalus              |   |
|  +----------------------------------------------------------------------+   |
|                                  |                                          |
|  +-------------------------------+--------------------------------------+   |
|  |                         cardano-node (Haskell)                       |   |
|  |                    Full node syncing Cardano blockchain              |   |
|  +----------------------------------------------------------------------+   |
+-----------------------------------------------------------------------------+

Technology Stack

Layer Technology Location
Desktop Framework Electron 24.2.0 Root package.json
UI Library React 16.14.0 source/renderer/
State Management MobX 5.15.7 source/renderer/app/stores/
Component Library react-polymorph 1.0.4 Widgets and forms
Styling SCSS Modules Co-located with components
Routing React Router 5.2.0 Hash history
i18n react-intl 2.9.0 EN, JA locales
Build System Nix + Webpack 5 flake.nix, webpack configs
Testing Jest + Cucumber tests/, *.test.tsx
Hardware Wallets Ledger, Trezor @cardano-foundation/ledgerjs, @trezor/connect

Key Directories

daedalus/
├── source/
│   ├── main/                    # Electron main process
│   │   ├── cardano/             # Node/wallet management
│   │   ├── ipc/                 # IPC handlers
│   │   ├── menus/               # Native menus
│   │   ├── trezor/              # Trezor integration
│   │   ├── utils/               # Logging, processes
│   │   └── windows/             # Window management
│   ├── renderer/                # Electron renderer (React)
│   │   └── app/
│   │       ├── actions/         # MobX actions
│   │       ├── api/             # cardano-wallet API client
│   │       ├── components/      # React components (23 categories)
│   │       ├── containers/      # Container components
│   │       ├── stores/          # MobX stores
│   │       ├── themes/          # Theme definitions
│   │       └── i18n/            # Internationalization
│   └── common/                  # Shared code
│       ├── ipc/                 # IPC API contracts
│       └── types/               # TypeScript types
├── storybook/                   # Component stories
├── tests/                       # Cucumber E2E tests
├── installers/                  # Platform installers
├── nix/                         # Nix configuration
├── translations/                # i18n translation files
└── utils/                       # API importers, test wallets

Quick Commands

Development Environment

# Enter Nix development shell (required first)
yarn nix:mainnet          # Mainnet
yarn nix:preprod          # Preprod testnet
yarn nix:preview          # Preview testnet

# Start development mode
yarn dev                  # Runs both main and renderer

Building

yarn build                # Production build
yarn build:main           # Build main process only
yarn build:renderer       # Build renderer only
yarn package              # Create installer

Testing

yarn test:unit            # Cucumber unit tests
yarn test:e2e             # Cucumber E2E tests
yarn test:jest            # Jest tests
yarn storybook            # Component development

Code Quality

yarn lint                 # ESLint
yarn compile              # TypeScript check
yarn prettier:check       # Prettier check
yarn check:all            # Run all checks

Wallet Importers (Testing)

yarn shelley:wallet:importer    # Import Shelley test wallets
yarn byron:wallet:importer      # Import Byron test wallets
yarn mary:wallet:importer       # Import Mary test wallets

Security Notes

  • Never commit secrets or private keys
  • Daedalus stores wallet data in user's app data directory
  • Hardware wallet signing happens on device, not in Daedalus
  • Recovery phrases are never stored unencrypted