ace

command module
v0.0.0-...-3bf5e7c Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 3, 2026 License: ISC Imports: 69 Imported by: 0

README

ACE — Amortized Compute Equity

A proof-of-work chain that pays for near misses, so nobody has to join a pool.

ACE is a fork of btcd. The network, database, script engine, mempool and headers-first sync are btcd's. What ACE changes is the proof of work and who gets paid for it.


The idea

Proof of work does not centralise because hash rate is unequal. It centralises because reward is lumpy.

A miner with one part in a million of a network finds a block roughly once every two years. Their expected income is perfectly fair; their realised income is nothing, in 96 % of months. Nobody runs a business on that, so they sell their hash rate to an operator who runs enough of it that the variance averages out — and that operator now decides which transactions their hash rate confirms. Pools, not whales, are the centralisation.

ACE removes the reason to pool instead of policing the result.

Miners publish fruits: proofs a few hundred times easier than a block, found by the same nonce search at no extra cost, hanging off a recent tip. Every block harvests all fresh fruits and pays 99 % of the subsidy per fruit at a fixed rate, plus four fifths of its transaction fees. This is precisely the object a mining pool already calls a share — ACE just pays for it on chain, so the miner never has to hand their hash rate to anybody.

Expected revenue is unchanged and still exactly proportional to hash rate, which is what keeps proof of work secure. Income variance falls by 496× on the subsidy, and by 79× even on a chain where fees are half of all revenue, which is what makes solo mining viable at 1/300th of the previous scale.

Two supporting rules close the escape hatches:

  • ACEHash is memory-bandwidth-bound over a 2 GiB dataset, so the efficient frontier is a commodity GPU and an ASIC has to ship DRAM before it can compete.
  • The puzzle is non-outsourceable: the predicate d < target cannot be evaluated without the payout secret, so an operator cannot have somebody else search on their behalf without handing over the ability to spend the reward.

Full argument, parameters, analysis and limitations: doc/WHITEPAPER.md. GPU compute request: doc/GRANT.md.


Measured, not asserted

Reference implementation, pure Go, single core, AMD Ryzen 5 5625U. Reproduce with go test -bench . ./acehash/ and go run ./cmd/acesim.

ACEHash attempt, 2 GiB dataset resident      5.85 µs
ACEHash attempt, recomputing every element  262.9  µs
memory-hardness margin                        44.9x

income variance reduction, zero fees           496x  (97% of the 513x ceiling)
income variance reduction, 10% fee revenue    373x  (74x without fee smoothing)
income variance reduction, 50% fee revenue     79x  (3.9x without fee smoothing)
smallest viable solo miner, Bitcoin        3.2e-04   (1 GPU among 3,162)
smallest viable solo miner, ACE           <=1.0e-06  (1 GPU among >=1,000,000)

realised issuance over 200k blocks          100.3%   (69.2% under a per-block cap)
new unspent outputs/yr, 10k miners           22.4M   (269M if fruits paid at once)

And at production reward parameters on a real chain (F=512, 240-block payout rota, 360 blocks — go test -tags soak -run TestACEMainnetScale ./blockchain/):

fruits harvested per block                   510.6   (nominal F=512)
realised issuance                            99.92%  of schedule
rota conservation                            every credit paid exactly once
largest block                                87,564 bytes
ProcessBlock                                  58 ms  p50 (was 243 ms)
  -> initial sync                             8.4 hours per year of chain

Fruit proofs verify in parallel and the ancestor walk is memoised; per block that is now within ~1.4x of Bitcoin's. See whitepaper §8.9.

And on a real chain, from TestACEChainEndToEnd — three miners at 32:8:1 hash rate, 24 blocks, through the production ProcessBlock path:

whale  weight 3200  blocks 20  fruits 183  paid 79,976,871,523
farm   weight  800  blocks  4  fruits  62  paid 25,910,628,316
solo   weight  100  blocks  0  fruits   3  paid  1,462,500,000

The solo miner found zero blocks and was still paid. That row is the whole point.

Two real nodes, --simnet: a mining node produced eight blocks via the generate RPC and a second node synced all eight over the peer-to-peer protocol with zero rejections.


Building

go build ./...                    # node, wallet tools, simulator
go test ./...                     # full suite
go test -tags rpctest ./integration/   # spawns real nodes over the p2p protocol

The integration suite is behind a build tag, as it is upstream: it compiles the node, launches several of them, and binds fixed ports, which does not belong in a routine go test ./.... Both commands pass. Four staged soft-fork activation tests are skipped with a reason, because ACE activates CSV, segregated witness and taproot at height 1 and so has no defined/started/locked-in/active progression for them to walk through.

Go 1.25 or later. No cgo.

go run ./cmd/acesim              # fairness simulation
go run ./cmd/acesim -json        # machine-readable
go run ./cmd/acegenesis          # re-mine the genesis blocks
go test -bench . ./acehash/      # proof-of-work benchmarks

Layout

Everything ACE adds or changes:

acehash/            proof of work: dataset, search, verification
fruit/              fruit objects, merkle commitment, reward accounting
asert/              per-block difficulty from a fixed anchor
fruitpool/          unharvested fruits awaiting a block
blockchain/ace.go   every consensus rule that differs from Bitcoin
mining/ace.go       template assembly, payout table, two-for-one search
chaincfg/ace.go     per-network ACE parameters
cmd/acesim/         fairness simulator
cmd/acegenesis/     genesis miner
doc/                whitepaper, grant request, benchmark records

Everything else is btcd, with two removals: signet, because a network whose blocks are signed by a trusted party is incoherent in a project about permissionless mining, and testnet4, because one testnet is enough.


Parameters

mainnet
Block spacing 60 s
Subsidy 50 ACE, halving every 2,100,000 blocks (~4 years)
Supply 210,000,000 ACE as a long-run mean, not a hard per-block cap
Base unit 1 ACE = 100,000,000 chips
Proof of work ACEHash, 2 GiB dataset, 32 lookups, epoch every 2048 blocks
Fruits per block 512 rising to 1024 with difficulty, harvestable for 60 blocks
Reward split 99.0 % fruits / 0.6 % harvest bonus / 0.4 % block
Fee split 20 % block finder / 80 % fruits, remainder burned
Payout rota fruit credits settle every 240 blocks (4 h), max 4096 payouts/block
Difficulty ASERT, 2-hour half-life, anchored at genesis
Header 182 bytes (80 + 102-byte solution)
P2P / RPC 9911 / 9912
Mining --miningkey=<WIF>; ACE cannot mine to an address
Addresses A… (P2PKH), C… (P2SH), ace1… (bech32)
Premine none — the genesis coinbase creates zero coins

Test status

Honest version, because a green badge that hides skips is worse than no badge.

ACE's own consensus rules are covered. TestACEChainEndToEnd mines a real chain with three differently-sized miners and checks who got paid. TestACEBlockRejectsTampering and TestGreedyCoinbaseIsRejected check that each new rule actually rejects something. acehash, fruit, asert, chaincfg and the ACE wire format each have full unit suites, including the non-outsourceability property, the variance optimum, and the difficulty loop's response to a hash-rate shock.

A number of inherited btcd tests are skipped, each with an explicit reason in its t.Skip string. They fall into two groups: tests that replay captured Bitcoin blocks (blk_0_to_4.dat.bz2, 277647.dat) or assert against hardcoded Bitcoin addresses, keys and wire bytes — none of which can be valid under ACE parameters; and fullblocktests, several hundred blocks hand-written against Bitcoin consensus, whose port requires regenerating every one with a real ACEHash solution. That port has not been done and the skips say so.

Ten defects were found by building, running and simulating rather than by reading the design. Six were coding errors: a block's own proof could be harvested as an explicit fruit and paid twice; testnet's difficulty floor made the scaled fruit target overflow 256 bits; the daemon could not mine at all, because nothing configured a mining key and the fruit pool was never drained after a harvest; and every transaction identifier in a block received from a peer was silently wrong, because btcutil sliced transactions out of the cached serialisation at Bitcoin's 80-byte header offset.

That last one is instructive: locally built blocks take a different code path, so the unit tests, the end-to-end test and single-node mining all passed while peer-to-peer sync could never have worked. It was found by starting two nodes.

The fifth was found the same way: a reorg left the fruit pool holding fruits whose parent was no longer an ancestor, so the miner built a template, had it rejected, rebuilt it and had it rejected again, at full CPU, forever.

The other three were not errors — they were design rules that looked right and were quantitatively wrong. A per-block issuance cap destroyed 31 % of all issuance to the concavity of min(n, F), making the real supply ceiling 145 M rather than 210 M. A constant fruit count gave the fairness claim an undisclosed price ceiling, since payout cadence decayed in proportion to adoption. And paying every fruit in the block that harvested it would have created more unspent outputs in one year than Bitcoin has in its history. A tenth was not a code defect but a false claim: the whitepaper asserted that hoarding your own fruits is "pure downside". Modelling strategic miners showed it is worth up to +0.54 % of revenue and rises with hash-rate share, because withholding a fruit captures the harvest bonus attached to it. The magnitude is bounded by the harvest pot, which makes HarvestShareBP = 0.6 % load bearing rather than incidental.

All ten are fixed — in the code where they were code, in the document where the document was wrong — and written up in whitepaper §6.1 with the figures that condemned them.

One further defect was in the test harness rather than the chain, and it matters because it was hiding the state of the suite: rpctest's memory wallet was never adapted to ACE — it watched an HD-derived address while coinbases pay HarnessMiningKey, never registered that key with the node's transaction filter, and signed legacy inputs where ACE pays pay-to-witness-public-key-hash. It was therefore never funded, and seven integration tests failed for want of coins. An earlier revision of this README implied the integration suite was green. It was not.


Security review

Six independent reviews of the consensus code, with the serious findings verified by running code: doc/AUDIT-FINDINGS.md.

It is not a third-party audit and does not claim to be. The headline is that a critical flaw was found and fixed — publishing two proofs leaked the miner's payout secret, because every proof from one search shared a one-time key and two of them solve for the key outright.

Every finding in that document is now closed except items that are cosmetic, unreachable, or deferred as policy decisions. Nothing open can halt the chain, forge a proof, steal a reward, or split two honest nodes. Coverage of the ACE consensus delta is 80–99 % per file, measured rather than asserted.

ACE is still not ready for a mainnet launch, for reasons that are now about assurance rather than known defects: the GPU memory-hardness margin has never been measured and is the design's central claim; the fullblocktests corpus is unported; and there is no third-party audit and no independent implementation to cross-check consensus against. The last two cannot be produced from inside the project.


Status

Unlaunched. No live network, no seeders, no audit, no GPU kernel, no independent implementation to cross-check consensus against. The genesis blocks are mined and the chain runs end to end in tests. That is the current state and nothing more is claimed.

Read doc/WHITEPAPER.md §8 — the limitations section is longer than this README's summary and it is the part worth reading first.

The upstream btcd README is preserved at doc/UPSTREAM-README.md.


Licence

ISC, inherited from btcd. See LICENSE.

Documentation

Overview

btcd is a full-node bitcoin implementation written in Go.

The default options are sane for most users. This means btcd will work 'out of the box' for most users. However, there are also a wide variety of flags that can be used to control it.

The following section provides a usage overview which enumerates the flags. An interesting point to note is that the long form of all of these options (except -C) can be specified in a configuration file that is automatically parsed when btcd starts up. By default, the configuration file is located at ~/.btcd/btcd.conf on POSIX-style operating systems and %LOCALAPPDATA%\btcd\btcd.conf on Windows. The -C (--configfile) flag, as shown below, can be used to override this location.

Usage:

btcd [OPTIONS]

Application Options:

    --addcheckpoint=        Add a custom checkpoint.  Format:
                            '<height>:<hash>'
-a, --addpeer=              Add a peer to connect with at startup
    --addrindex             Maintain a full address-based transaction index
                            which makes the searchrawtransactions RPC
                            available
    --banduration=          How long to ban misbehaving peers.  Valid time
                            units are {s, m, h}.  Minimum 1 second (default:
                            24h0m0s)
    --banthreshold=         Maximum allowed ban score before disconnecting
                            and banning misbehaving peers. (default: 100)
    --blockmaxsize=         Maximum block size in bytes to be used when
                            creating a block (default: 750000)
    --blockminsize=         Minimum block size in bytes to be used when
                            creating a block
    --blockmaxweight=       Maximum block weight to be used when creating a
                            block (default: 3000000)
    --blockminweight=       Minimum block weight to be used when creating a
                            block
    --blockprioritysize=    Size in bytes for high-priority/low-fee
                            transactions when creating a block (default:
                            50000)
    --blocksonly            Do not accept transactions from remote peers.
-C, --configfile=           Path to configuration file
    --connect=              Connect only to the specified peers at startup
    --cpuprofile=           Write CPU profile to the specified file
-b, --datadir=              Directory to store data
    --dbtype=               Database backend to use for the Block Chain
                            (default: ffldb)
-d, --debuglevel=           Logging level for all subsystems {trace, debug,
                            info, warn, error, critical} -- You may also
                            specify
                            <subsystem>=<level>,<subsystem2>=<level>,... to
                            set the log level for individual subsystems --
                            Use show to list available subsystems (default:
                            info)
    --dropaddrindex         Deletes the address-based transaction index from
                            the database on start up and then exits.
    --dropcfindex           Deletes the index used for committed filtering
                            (CF) support from the database on start up and
                            then exits.
    --droptxindex           Deletes the hash-based transaction index from the
                            database on start up and then exits.
    --externalip=           Add an ip to the list of local addresses we claim
                            to listen on to peers
    --generate              Generate (mine) bitcoins using the CPU
    --limitfreerelay=       Limit relay of transactions with no transaction
                            fee to the given amount in thousands of bytes per
                            minute (default: 15)
    --listen=               Add an interface/port to listen for connections
                            (default all interfaces port: 8333, testnet:
                            18333, signet: 38333)
    --logdir=               Directory to log output
    --maxorphantx=          Max number of orphan transactions to keep in
                            memory (default: 100)
    --maxpeers=             Max number of inbound and outbound peers
                            (default: 125)
    --miningaddr=           Add the specified payment address to the list of
                            addresses to use for generated blocks -- At least
                            one address is required if the generate option is
                            set
    --minrelaytxfee=        The minimum transaction fee in BTC/kB to be
                            considered a non-zero fee. (default: 1e-05)
    --nobanning             Disable banning of misbehaving peers
    --nocfilters            Disable committed filtering (CF) support
    --nocheckpoints         Disable built-in checkpoints.  Don't do this
                            unless you know what you're doing.
    --nodnsseed             Disable DNS seeding for peers
    --nolisten              Disable listening for incoming connections --
                            NOTE: Listening is automatically disabled if the
                            --connect or --proxy options are used without
                            also specifying listen interfaces via --listen
    --noonion               Disable connecting to tor hidden services
    --nopeerbloomfilters    Disable bloom filtering support
    --norelaypriority       Do not require free or low-fee transactions to
                            have high priority for relaying
    --norpc                 Disable built-in RPC server -- NOTE: The RPC
                            server is disabled by default if no
                            rpcuser/rpcpass or rpclimituser/rpclimitpass is
                            specified
    --notls                 Disable TLS for the RPC server -- NOTE: This is
                            only allowed if the RPC server is bound to
                            localhost
    --onion=                Connect to tor hidden services via SOCKS5 proxy
                            (eg. 127.0.0.1:9050)
    --onionpass=            Password for onion proxy server
    --onionuser=            Username for onion proxy server
    --profile=              Enable HTTP profiling on given port -- NOTE port
                            must be between 1024 and 65536
    --proxy=                Connect via SOCKS5 proxy (eg. 127.0.0.1:9050)
    --proxypass=            Password for proxy server
    --proxyuser=            Username for proxy server
    --regtest               Use the regression test network
    --rejectnonstd          Reject non-standard transactions regardless of
                            the default settings for the active network.
    --relaynonstd           Relay non-standard transactions regardless of the
                            default settings for the active network.
    --rpccert=              File containing the certificate file
    --rpckey=               File containing the certificate key
    --rpclimitpass=         Password for limited RPC connections
    --rpclimituser=         Username for limited RPC connections
    --rpclisten=            Add an interface/port to listen for RPC
                            connections (default port: 8334, testnet: 18334)
    --rpcmaxclients=        Max number of RPC clients for standard
                            connections (default: 10)
    --rpcmaxconcurrentreqs= Max number of concurrent RPC requests that may be
                            processed concurrently (default: 20)
    --rpcmaxwebsockets=     Max number of RPC websocket connections (default:
                            25)
    --rpcquirks             Mirror some JSON-RPC quirks of Bitcoin Core --
                            NOTE: Discouraged unless interoperability issues
                            need to be worked around
-P, --rpcpass=              Password for RPC connections
-u, --rpcuser=              Username for RPC connections
    --sigcachemaxsize=      The maximum number of entries in the signature
                            verification cache (default: 100000)
    --simnet                Use the simulation test network
    --testnet               Use the test network
    --torisolation          Enable Tor stream isolation by randomizing user
                            credentials for each connection.
    --trickleinterval=      Minimum time between attempts to send new
                            inventory to a connected peer (default: 10s)
    --txindex               Maintain a full hash-based transaction index
                            which makes all transactions available via the
                            getrawtransaction RPC
    --uacomment=            Comment to add to the user agent -- See BIP 14
                            for more information.
    --upnp                  Use UPnP to map our listening port outside of NAT
-V, --version               Display version information and exit
    --whitelist=            Add an IP network or IP that will not be banned.
                            (eg. 192.168.1.0/24 or ::1)

Help Options:

-h, --help           Show this help message

Directories

Path Synopsis
Package acehash implements ACEHash, the proof-of-work function of the ACE network.
Package acehash implements ACEHash, the proof-of-work function of the ACE network.
base58
Package base58 provides an API for working with modified base58 and Base58Check encodings.
Package base58 provides an API for working with modified base58 and Base58Check encodings.
bech32
Package bech32 provides a Go implementation of the bech32 format specified in BIP 173.
Package bech32 provides a Go implementation of the bech32 format specified in BIP 173.
Package addrmgr implements concurrency safe Bitcoin address manager.
Package addrmgr implements concurrency safe Bitcoin address manager.
Package asert implements ACE's difficulty control loop, an absolutely scheduled exponentially rising target (aserti3-2d).
Package asert implements ACE's difficulty control loop, an absolutely scheduled exponentially rising target (aserti3-2d).
Package blockchain implements bitcoin block handling and chain selection rules.
Package blockchain implements bitcoin block handling and chain selection rules.
fullblocktests
Package fullblocktests provides a set of block consensus validation tests.
Package fullblocktests provides a set of block consensus validation tests.
indexers
Package indexers implements optional block chain indexes.
Package indexers implements optional block chain indexes.
Package btcec implements support for the elliptic curves needed for bitcoin.
Package btcec implements support for the elliptic curves needed for bitcoin.
Package btcjson provides primitives for working with the bitcoin JSON-RPC API.
Package btcjson provides primitives for working with the bitcoin JSON-RPC API.
Package btcutil provides bitcoin-specific convenience functions and types.
Package btcutil provides bitcoin-specific convenience functions and types.
gcs
Package gcs provides an API for building and using a Golomb-coded set filter.
Package gcs provides an API for building and using a Golomb-coded set filter.
hdkeychain
Package hdkeychain provides an API for bitcoin hierarchical deterministic extended keys (BIP0032).
Package hdkeychain provides an API for bitcoin hierarchical deterministic extended keys (BIP0032).
txsort
Package txsort provides the transaction sorting according to BIP 69.
Package txsort provides the transaction sorting according to BIP 69.
Package chaincfg defines chain configuration parameters.
Package chaincfg defines chain configuration parameters.
Package chainhash provides abstracted hash functionality.
Package chainhash provides abstracted hash functionality.
cmd
acegenesis command
Command acegenesis mines the genesis block solution for each ACE network and prints it as Go source, ready to be pasted into chaincfg/genesis.go.
Command acegenesis mines the genesis block solution for each ACE network and prints it as Go source, ready to be pasted into chaincfg/genesis.go.
acesim command
Command acesim measures how unequally a proof-of-work reward schedule treats miners of different sizes.
Command acesim measures how unequally a proof-of-work reward schedule treats miners of different sizes.
addblock command
btcctl command
findcheckpoint command
gencerts command
Package connmgr implements a generic Bitcoin network connection manager.
Package connmgr implements a generic Bitcoin network connection manager.
Package database provides a block and metadata storage database.
Package database provides a block and metadata storage database.
cmd/dbtool command
ffldb
Package ffldb implements a driver for the database package that uses leveldb for the backing metadata and flat files for block storage.
Package ffldb implements a driver for the database package that uses leveldb for the backing metadata and flat files for block storage.
internal/treap
Package treap implements a treap data structure that is used to hold ordered key/value pairs using a combination of binary search tree and heap semantics.
Package treap implements a treap data structure that is used to hold ordered key/value pairs using a combination of binary search tree and heap semantics.
Package fruit implements ACE's reward-smoothing layer.
Package fruit implements ACE's reward-smoothing layer.
Package fruitpool holds the fruits a node has heard about but that no block has harvested yet.
Package fruitpool holds the fruits a node has heard about but that no block has harvested yet.
rpctest
Package rpctest provides a btcd-specific RPC testing harness crafting and executing integration tests by driving a `btcd` instance via the `RPC` interface.
Package rpctest provides a btcd-specific RPC testing harness crafting and executing integration tests by driving a `btcd` instance via the `RPC` interface.
internal
Package mempool provides a policy-enforced pool of unmined bitcoin transactions.
Package mempool provides a policy-enforced pool of unmined bitcoin transactions.
Package netsync implements a concurrency safe block syncing protocol.
Package netsync implements a concurrency safe block syncing protocol.
Package peer provides a common base for creating and managing Bitcoin network peers.
Package peer provides a common base for creating and managing Bitcoin network peers.
Package psbt is an implementation of Partially Signed Bitcoin Transactions (PSBT).
Package psbt is an implementation of Partially Signed Bitcoin Transactions (PSBT).
Package rpcclient implements a websocket-enabled Bitcoin JSON-RPC client.
Package rpcclient implements a websocket-enabled Bitcoin JSON-RPC client.
Package txscript implements the bitcoin transaction script language.
Package txscript implements the bitcoin transaction script language.
Package wire implements the bitcoin wire protocol.
Package wire implements the bitcoin wire protocol.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL