first review

.cargo/config.toml

@@ -0,0 +1,7 @@
+[alias]
+test_unit = "test --features automation,use-test-vk"
+test_integration = "test --workspace --all-features -p core test:: -- --test-threads 7"
+test_integration_release = "test --release --workspace --all-features -p core test:: -- --test-threads 7"
+build_console = '''
+build -p clementine-core --all-features --config build.rustflags=["--cfg","tokio_unstable"]
+'''

.dockerignore

@@ -0,0 +1,22 @@
+# exclude everything
+*
+
+# include source files
+!/circuits-lib
+!/.cargo
+!/risc0-circuits
+!/bridge-circuit-host
+!/core
+!/scripts
+!Cargo.lock
+!Cargo.toml
+
+# include for vergen constants
+!/.git
+
+# include licenses
+!LICENSE-*
+!LICENSE
+
+# exclude bitvm cache (for local builders who forgot to delete it)
+**/bitvm_cache*.bin

.env.example

@@ -0,0 +1,88 @@
+READ_CONFIG_FROM_ENV=1
+
+HOST=127.0.0.1
+PORT=17000
+INDEX=0
+SECRET_KEY=1111111111111111111111111111111111111111111111111111111111111111
+
+WINTERNITZ_SECRET_KEY=2222222222222222222222222222222222222222222222222222222222222222
+
+VERIFIERS_PUBLIC_KEYS=034f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa,02466d7fcae563e5cb09a0d1870bb580344804617879a14949cf22285f1bae3f27,023c72addb4fdf09af94f0c94d7fe92a386a7e70cf8a1d85916386bb2535c7b1b1,032c0b7cf95324a07d05398b240174dc0c2be444d96b159aa6c7f7b1e668680991
+NUM_VERIFIERS=4
+
+OPERATOR_XONLY_PKS=4f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa,466d7fcae563e5cb09a0d1870bb580344804617879a14949cf22285f1bae3f27
+NUM_OPERATORS=2
+OPERATOR_WITHDRAWAL_FEE_SATS=100000
+
+BITCOIN_RPC_URL=http://127.0.0.1:18443/wallet/admin
+BITCOIN_RPC_USER=admin
+BITCOIN_RPC_PASSWORD=admin
+
+MEMPOOL_API_HOST=https://mempool.space/
+MEMPOOL_API_ENDPOINT=api/v1/fees/recommended
+
+DB_HOST=127.0.0.1
+DB_PORT=5432
+DB_USER=clementine
+DB_PASSWORD=clementine
+DB_NAME=clementine
+
+CITREA_RPC_URL=http://127.0.0.1:12345
+CITREA_LIGHT_CLIENT_PROVER_URL=http://127.0.0.1:12346
+BRIDGE_CONTRACT_ADDRESS=3100000000000000000000000000000000000002
+
+HEADER_CHAIN_PROOF_PATH=../core/src/test/data/first_1.bin
+
+VERIFIER_ENDPOINTS=http://127.0.0.1:17001,http://127.0.0.1:17002,http://127.0.0.1:17003,http://127.0.0.1:17004
+OPERATOR_ENDPOINTS=http://127.0.0.1:17005,http://127.0.0.1:17006
+
+OPERATOR_REIMBURSEMENT_ADDRESS=32iVBEu4dxkUQk9dJbZUiBiQdmypcEyJRf
+OPERATOR_COLLATERAL_FUNDING_OUTPOINT=04bec3b3d996e4db2ac6175101bc9f281e7dba3029de9f4201d09c0d53b0ccf8:1
+
+TELEMETRY_HOST=0.0.0.0
+TELEMETRY_PORT=8081
+
+AGGREGATOR_VERIFICATION_ADDRESS=0x242fbec93465ce42b3d7c0e1901824a2697193fd
+
+READ_PARAMSET_FROM_ENV=1
+
+NETWORK=regtest
+NUM_ROUND_TXS=3
+NUM_KICKOFFS_PER_ROUND=10
+NUM_SIGNED_KICKOFFS=2
+BRIDGE_AMOUNT=1000000000
+KICKOFF_AMOUNT=0
+OPERATOR_CHALLENGE_AMOUNT=200000000
+COLLATERAL_FUNDING_AMOUNT=99000000
+KICKOFF_BLOCKHASH_COMMIT_LENGTH=40
+WATCHTOWER_CHALLENGE_BYTES=144
+WINTERNITZ_LOG_D=4
+USER_TAKES_AFTER=200
+OPERATOR_CHALLENGE_TIMEOUT_TIMELOCK=144
+OPERATOR_CHALLENGE_NACK_TIMELOCK=432
+DISPROVE_TIMEOUT_TIMELOCK=720
+ASSERT_TIMEOUT_TIMELOCK=576
+OPERATOR_REIMBURSE_TIMELOCK=12
+WATCHTOWER_CHALLENGE_TIMEOUT_TIMELOCK=288
+TIME_TO_SEND_WATCHTOWER_CHALLENGE=216
+LATEST_BLOCKHASH_TIMEOUT_TIMELOCK=360
+FINALITY_DEPTH=1
+START_HEIGHT=8148
+GENESIS_HEIGHT=8148
+GENESIS_CHAIN_STATE_HASH=1111111111111111111111111111111111111111111111111111111111111111
+HEADER_CHAIN_PROOF_BATCH_SIZE=100
+BRIDGE_NONSTANDARD=true
+
+SERVER_CERT_PATH="certs/server/server.pem"
+SERVER_KEY_PATH="certs/server/server.key"
+CA_CERT_PATH="certs/ca/ca.pem"
+CLIENT_CERT_PATH="certs/client/client.pem"
+CLIENT_KEY_PATH="certs/client/client.key"
+AGGREGATOR_CERT_PATH="certs/aggregator/aggregator.pem"
+CLIENT_VERIFICATION=true
+SECURITY_COUNCIL=1:50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0
+
+CITREA_RPC_URL=http://127.0.0.1:1234
+CITREA_LIGHT_CLIENT_PROVER_URL=http://127.0.0.1:1235
+CITREA_CHAIN_ID=5655
+BRIDGE_CONTRACT_ADDRESS=3100000000000000000000000000000000000002

.githooks/pre-commit

@@ -0,0 +1,16 @@
+#!/bin/sh
+
+if ! command -v cargo-fmt &> /dev/null; then
+    echo "cargo fmt is not installed. Please install it."
+    exit 1
+fi
+
+echo "Checking code formatting..."
+if ! cargo +nightly fmt --all -- --check; then
+    echo "Code is not properly formatted. Please run 'cargo +nightly fmt --all'."
+    echo "**After formatting, add the changes to your commit using 'git add' and commit again.**"
+    exit 1
+fi
+
+echo "Code formatting check passed."
+exit 0

.github/ISSUE_TEMPLATE/bug_issue.yaml

@@ -0,0 +1,46 @@
+name: Bug Template
+description: This issue template is used for bug reports.
+assignees: []
+labels: []
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please fill out the following sections to help us reproduce and fix the bug.
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected Behavior
+      placeholder: "Explain what should happen"
+    validations:
+      required: true
+
+  - type: textarea
+    id: current-behavior
+    attributes:
+      label: Current Behavior
+      placeholder: "Explain what happens instead of the expected behavior"
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps-to-reproduce
+    attributes:
+      label: Steps to Reproduce
+      placeholder: "Provide an unambiguous set of steps to reproduce the bug"
+    validations:
+      required: true
+
+  - type: textarea
+    id: possible-solutions
+    attributes:
+      label: Possible Solutions or Workarounds
+      placeholder: "Optional solution or workaround suggestions"
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes
+      placeholder: "Optional final notes"

.github/ISSUE_TEMPLATE/improvement_issue.yaml

@@ -0,0 +1,14 @@
+
+name: Improvement Proposal Template
+description: This issue template is used for proposing any kind of improvements.
+assignees: []
+labels: []
+body:
+  - type: textarea
+    id: issue-description
+    attributes:
+      placeholder: "Proposal description."
+      label: Proposal Description
+      description: "Describe the improvement idea, why we need it, how can it be done and how hard will it be (how much time it needs) to implement."
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/task_issue.yaml

@@ -0,0 +1,40 @@
+
+name: Task Template
+description: This issue template is used for giving tasks to group members.
+assignees: []
+labels: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+          Please do not forget to add **assignees** and **labels** to this issue.
+          State your tasks explicitly       
+  - type: textarea
+    id: issue-description
+    attributes:
+      placeholder: "Issue description."
+      label: Issue Description
+      description: "Describe the task and why wee need it. It can be multi-tasked issue also."
+    validations:
+      required: true
+  - type: textarea
+    id: step-details
+    attributes:
+      value: | 
+              Parts of the task:
+              - [ ] ...(1)
+              - [ ] ...(2)
+              - [ ] ...(3)
+      label: Tasks
+      description: "Parts of the task"
+  - type: input
+    id: deadline
+    attributes:
+      label: Deadline of the Issue
+      description: "Please provide a deadline for the issue."
+      placeholder: "01.01.1970 - Monday - 23:59"
+    validations:
+      required: true
+
+
+

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+# Description
+
+Describe what this pull request does, here.
+
+## Linked Issues
+
+- Closes # (issue, if applicable)
+- Related to # (issue)
+
+## Testing
+
+Describe how these changes were tested. If you've added new features, have you
+added unit tests?
+
+## Docs
+
+Describe where this code is documented. If it changes a documented interface,
+have the docs been updated?

.github/actions/build-prerequisites/action.yml

@@ -0,0 +1,11 @@
+# Start required services for building Clementine.
+
+name: Clementine Build Services
+description: 'Start services required for building Clementine'
+
+runs:
+  using: "composite"
+
+  steps:
+  - name: Install Protoc
+    uses: arduino/setup-protoc@v3

.github/actions/test-prerequisites/action.yml

@@ -0,0 +1,69 @@
+# Start required services for testing Clementine.
+
+name: Clementine Test Services
+description: "Start services required for testing Clementine"
+
+inputs:
+  github_token:
+    description: "GitHub token for authentication"
+    required: true
+
+runs:
+  using: "composite"
+
+  steps:
+    - name: Cache bitvm cache files
+      uses: actions/cache@v4
+      id: cache-bitvm
+      with:
+        path: |
+          core/bitvm_cache.bin
+          core/bitvm_cache_dev.bin
+        key: bitvm-cache-05-08-2025
+
+    - name: Download bitvm cache bin
+      if: steps.cache-bitvm.outputs.cache-hit != 'true'
+      shell: bash
+      run: wget https://static.testnet.citrea.xyz/common/bitvm_cache.bin -O core/bitvm_cache.bin
+
+    - name: Download bitvm cache dev bin
+      if: steps.cache-bitvm.outputs.cache-hit != 'true'
+      shell: bash
+      run: wget https://static.testnet.citrea.xyz/common/bitvm_cache_dev.bin -O core/bitvm_cache_dev.bin
+
+    - name: Cache Bitcoin binaries
+      uses: actions/cache@v4
+      id: cache-bitcoin
+      with:
+        path: |
+          bitcoin-29.0-x86_64-linux-gnu.tar.gz
+          bitcoin-29.0/
+        key: bitcoin-29.0-x86_64-linux-gnu
+
+    - name: Download Bitcoin
+      if: steps.cache-bitcoin.outputs.cache-hit != 'true'
+      shell: bash
+      run: wget https://bitcoincore.org/bin/bitcoin-core-29.0/bitcoin-29.0-x86_64-linux-gnu.tar.gz
+
+    - name: Unpack Bitcoin
+      if: steps.cache-bitcoin.outputs.cache-hit != 'true'
+      shell: bash
+      run: tar -xzvf bitcoin-29.0-x86_64-linux-gnu.tar.gz
+
+    - name: Set executable permissions
+      shell: bash
+      run: chmod +x bitcoin-29.0/bin/*
+
+    - name: Add bitcoin to path
+      shell: bash
+      run: echo "$PWD/bitcoin-29.0/bin" >> $GITHUB_PATH
+
+    - name: Install risc0
+      shell: bash
+      env:
+        GITHUB_TOKEN: ${{ inputs.github_token }}
+      run: |
+        curl -L https://risczero.com/install | bash
+        export PATH="$PATH:$HOME/.risc0/bin"
+        rzup install
+        rzup install rust 1.85.0

.github/workflows/auto_tag.yml

@@ -0,0 +1,41 @@
+name: Label PR on Breaking Change
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  label:
+    runs-on: ubicloud-standard-2
+
+    steps:
+      - name: Checkout PR
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Get changed files
+        id: files
+        run: |
+          {
+            echo "CHANGED<<EOF"
+            git diff --name-only ${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}
+            echo "EOF"
+          } >> $GITHUB_OUTPUT
+
+      - name: Check for deposit state changes
+        id: check
+        run: |
+          echo "${{ steps.files.outputs.CHANGED }}" | grep -E '^core/src/test/data/deposit_state_' && echo "match=true" >> $GITHUB_OUTPUT || echo "match=false" >> $GITHUB_OUTPUT
+
+      - name: Add label
+        if: steps.check.outputs.match == 'true'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.addLabels({
+              issue_number: context.payload.pull_request.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              labels: ['F-deposit-replace-needed']
+            })