Skip to content
Skills Library
Programming · Learning & explanation

bitcoin-mining-difficulty

/bitcoin-mining-difficulty

Difficulty adjustment algorithm: 2016-block re-target window, max 4x factor, time-warp considerations, real-world hashrate dynamics. USE WHEN: predicting next adjustment, understanding hashrate/ difficulty cycles, building mining analytics.

Licence
MIT
Last repository change
21.10.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Difficulty adjustment algorithm: 2016-block re-target window, max 4x factor, time-warp considerations, real-world hashrate dynamics. USE WHEN: predicting next adjustment, understanding hashrate/ difficulty cycles, building mining analytics.

Original author description

Difficulty adjustment algorithm: 2016-block re-target window, max 4x factor, time-warp considerations, real-world hashrate dynamics. USE WHEN: predicting next adjustment, understanding hashrate/ difficulty cycles, building mining analytics.

How it works

  1. Algorithm
  2. Time-warp protection
  3. Real-world dynamics
  4. Common adjustments
  5. Difficulty number vs hashrate
  6. Common bugs
  7. See also
Original SKILL.md headings · 64 lines, 252 words
SKILL.md preview
---
name: bitcoin-mining-difficulty
description: |
  Difficulty adjustment algorithm: 2016-block re-target window, max 4x
  factor, time-warp considerations, real-world hashrate dynamics.
  USE WHEN: predicting next adjustment, understanding hashrate/
  difficulty cycles, building mining analytics.
allowed-tools: Read, Grep, Glob
---

# Difficulty Adjustment

Bitcoin re-targets the difficulty every **2016 blocks** to maintain
~10-minute average block time despite hashrate fluctuations.

## Algorithm

```python
def next_difficulty(current_difficulty, actual_time, expected_time):
    # actual_time = sum of block_n.timestamp - block_(n-2015).timestamp
    # expected_time = 2016 * 10 * 60 = 1,209,600 seconds
    factor = expected_time / actual_time
    factor = clamp(factor, 0.25, 4.0)   # 4x max change per epoch
    return current_difficulty * factor
```

Implemented in `pow.cpp:CalculateNextWorkRequired()` in Bitcoin Core.

## Time-warp protection

Sequential blocks must have:
- `block.timestamp > MTP(last 11 blocks)`.
- `block.timestamp ≤ network_time + 2 hours` (avoids future-dated
  blocks).

These rules limit miner manipulation of timestamps to game the
adjustment.

## Real-world dynamics

- China mining ban (May 2021): hashrate dropped ~50% over weeks;
  difficulty took ~3 weeks to drop accordingly. Miners enjoyed
  high-revenue period during the lag.
- Halvings cause hashrate dips that recover over months.
- Seasonal fluctuations (China's wet season → cheaper hydropower
  → hashrate spikes).

## Common adjustments

Typical adjustments: 0.5% to 5% per epoch in normal conditions.
Large adjustments (10%+) signal major hashrate event (region ban,
ASIC manufacturing surge, etc.).

## Difficulty number vs hashrate

```
hashrate_estimate = difficulty * 2^32 / 600   # H/s
```

Where `2^32` = full nonce space probed for one solution at expected
target, and 600 seconds = average block time.

## Common bugs

- Computing actual_time incorrectly (off-by-one on block count).
- Forgetting the 4x cap → catastrophic divergence.
- Using block timestamps directly without MTP for time-locks.

## See also

- [pow/SKILL.md](../pow/SKILL.md)
- [stratum-v2/SKILL.md](../stratum-v2/SKILL.md)

Versions

The database has no other skills named bitcoin-mining-difficulty.

Database snapshot: 13.11.2026 · package version 8fd469416159 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95bitcoin-mining-pow
    Bitcoin Proof of Work: SHA256d on block header, target, nonce iteration, hashrate, mining math. USE WHEN: explaining mining mechanics, debugging mining software, designing mining-related apps.
  • 95blockchain-bitcoin
    Use this skill when asked about Bitcoin internals, Bitcoin Core, Bitcoin Script, Taproot, mining, Proof of Work, Lightning Network, BIP standards, Ordinals, BRC-20, Runes, Bitcoin L2s (Stacks, RSK, Babylon), and Bitcoin protocol development. Languages: C++, Rust, Python,…
  • 85bitcoin-l2-fractal-bitcoin
    Fractal Bitcoin: a Bitcoin Core-derived scaling chain with ~30s blocks and Cadence Mining (part merge-mined with Bitcoin, part permissionless, part Index Mining since FIP-101). Mainnet 9 Sept 2024. FIP-102 / fractald v0.4.0 hard-forked at block 2,100,000, combining the first and…
  • 100warp
    Warp is a terminal with command blocks and a built-in coding agent. Use this skill to write Warp Workflows (parameterized commands), share them through Warp Drive, set up themes, tab configs or launch configurations, and use blocks, notebooks and agent mode. Trigger words are…
  • 100warp
    Expert Warp terminal assistance covering AI command search, block-based navigation, workflows, team sharing, and session customization. Use when using Warp terminal, authoring custom Warp workflows, configuring AI prompts, or optimizing terminal command management.
  • 90difficulty-and-balancing
    Use when designing, tuning, or reviewing the difficulty or balance of any game system — encounter tuning, cost curves, dominant-strategy audits, dynamic difficulty adjustment (DDA), difficulty settings, and accessibility assists. Also use to diagnose "this is too hard/too easy",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.