READ THE CODE

Inside Bitcoin

The code behind the network, with room to understand it.

Stable release v32.1bitcoin/bitcoin · f0de87f04062 ↗3,020 source files · 47.5 MB stored on the server440 file guides

Release published 2026-10-28 · Snapshot fetched 2026-11-01. Latest stable release at fetch time; development branches and Git history are excluded. Only the selected code window and visible folders load here.

9,148 bytes · SHA-256 620db468b1c13968… · View upstream ↗

1#ifndef SECP256K1_ELLSWIFT_H
2#define SECP256K1_ELLSWIFT_H
3
4#include "secp256k1.h"
5
6#ifdef __cplusplus
7extern "C" {
8#endif
9
10/* This module provides an implementation of ElligatorSwift as well as a
11 * version of x-only ECDH using it (including compatibility with BIP324).
12 *
13 * ElligatorSwift is described in https://eprint.iacr.org/2022/759 by
14 * Chavez-Saab, Rodriguez-Henriquez, and Tibouchi. It permits encoding
15 * uniformly chosen public keys as 64-byte arrays which are indistinguishable
16 * from uniformly random arrays.
17 *
18 * Let f be the function from pairs of field elements to point X coordinates,
19 * defined as follows (all operations modulo p = 2^256 - 2^32 - 977)
20 * f(u,t):
21 * - Let C = 0xa2d2ba93507f1df233770c2a797962cc61f6d15da14ecd47d8d27ae1cd5f852,
22 *   a square root of -3.
23 * - If u=0, set u=1 instead.
24 * - If t=0, set t=1 instead.
25 * - If u^3 + t^2 + 7 = 0, multiply t by 2.
26 * - Let X = (u^3 + 7 - t^2) / (2 * t)
27 * - Let Y = (X + t) / (C * u)
28 * - Return the first in [u + 4 * Y^2, (-X/Y - u) / 2, (X/Y - u) / 2] that is an
29 *   X coordinate on the curve (at least one of them is, for any u and t).
30 *
31 * Then an ElligatorSwift encoding of x consists of the 32-byte big-endian
32 * encodings of field elements u and t concatenated, where f(u,t) = x.
33 * The encoding algorithm is described in the paper, and effectively picks a
34 * uniformly random pair (u,t) among those which encode x.
35 *
36 * If the Y coordinate is relevant, it is given the same parity as t.
37 *
38 * Changes w.r.t. the paper:
39 * - The u=0, t=0, and u^3+t^2+7=0 conditions result in decoding to the point
40 *   at infinity in the paper. Here they are remapped to finite points.
41 * - The paper uses an additional encoding bit for the parity of y. Here the
42 *   parity of t is used (negating t does not affect the decoded x coordinate,
43 *   so this is possible).
44 *
45 * For mathematical background about the scheme, see the doc/ellswift.md file.
46 */
47
48/** A pointer to a function used by secp256k1_ellswift_xdh to hash the shared X
49 *  coordinate along with the encoded public keys to a uniform shared secret.
50 *
51 *  Returns: 1 if a shared secret was successfully computed.
52 *           0 will cause secp256k1_ellswift_xdh to fail and return 0.
53 *           Other return values are not allowed, and the behaviour of
54 *           secp256k1_ellswift_xdh is undefined for other return values.
55 *  Out:     output:     pointer to an array to be filled by the function
56 *  In:      x32:        pointer to the 32-byte serialized X coordinate
57 *                       of the resulting shared point (will not be NULL)
58 *           ell_a64:    pointer to the 64-byte encoded public key of party A
59 *                       (will not be NULL)
60 *           ell_b64:    pointer to the 64-byte encoded public key of party B
61 *                       (will not be NULL)
62 *           data:       arbitrary data pointer that is passed through
63 */
64typedef int (*secp256k1_ellswift_xdh_hash_function)(
65    unsigned char *output,
66    const unsigned char *x32,
67    const unsigned char *ell_a64,
68    const unsigned char *ell_b64,
69    void *data
70);
71
72/** An implementation of an secp256k1_ellswift_xdh_hash_function which uses
73 *  SHA256(prefix64 || ell_a64 || ell_b64 || x32), where prefix64 is the 64-byte
74 *  array pointed to by data. */
75SECP256K1_API const secp256k1_ellswift_xdh_hash_function secp256k1_ellswift_xdh_hash_function_prefix;
76
77/** An implementation of an secp256k1_ellswift_xdh_hash_function compatible with
78 *  BIP324. It returns H_tag(ell_a64 || ell_b64 || x32), where H_tag is the
79 *  BIP340 tagged hash function with tag "bip324_ellswift_xonly_ecdh". Equivalent
80 *  to secp256k1_ellswift_xdh_hash_function_prefix with prefix64 set to
81 *  SHA256("bip324_ellswift_xonly_ecdh")||SHA256("bip324_ellswift_xonly_ecdh").
82 *  The data argument is ignored. */
83SECP256K1_API const secp256k1_ellswift_xdh_hash_function secp256k1_ellswift_xdh_hash_function_bip324;
84
85/** Construct a 64-byte ElligatorSwift encoding of a given pubkey.
86 *
87 *  Returns: 1 always.
88 *  Args:    ctx:        pointer to a context object
89 *  Out:     ell64:      pointer to a 64-byte array to be filled
90 *  In:      pubkey:     pointer to a secp256k1_pubkey containing an
91 *                       initialized public key
92 *           rnd32:      pointer to 32 bytes of randomness
93 *
94 * It is recommended that rnd32 consists of 32 uniformly random bytes, not
95 * known to any adversary trying to detect whether public keys are being
96 * encoded, though 16 bytes of randomness (padded to an array of 32 bytes,
97 * e.g., with zeros) suffice to make the result indistinguishable from
98 * uniform. The randomness in rnd32 must not be a deterministic function of
99 * the pubkey (it can be derived from the private key, though).
100 *
101 * It is not guaranteed that the computed encoding is stable across versions
102 * of the library, even if all arguments to this function (including rnd32)
103 * are the same.
104 *
105 * This function runs in variable time.
106 */
107SECP256K1_API int secp256k1_ellswift_encode(
108    const secp256k1_context *ctx,
109    unsigned char *ell64,
110    const secp256k1_pubkey *pubkey,
111    const unsigned char *rnd32
112) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4);
113
114/** Decode a 64-bytes ElligatorSwift encoded public key.
115 *
116 *  Returns: always 1
117 *  Args:    ctx:        pointer to a context object
118 *  Out:     pubkey:     pointer to a secp256k1_pubkey that will be filled
119 *  In:      ell64:      pointer to a 64-byte array to decode
120 *
121 * This function runs in variable time.
122 */
123SECP256K1_API int secp256k1_ellswift_decode(
124    const secp256k1_context *ctx,
125    secp256k1_pubkey *pubkey,
126    const unsigned char *ell64
127) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
128
129/** Compute an ElligatorSwift public key for a secret key.
130 *
131 *  Returns: 1: secret was valid, public key was stored.
132 *           0: secret was invalid, try again.
133 *  Args:    ctx:        pointer to a context object (not secp256k1_context_static)
134 *  Out:     ell64:      pointer to a 64-byte array to receive the ElligatorSwift
135 *                       public key
136 *  In:      seckey32:   pointer to a 32-byte secret key
137 *           auxrnd32:   (optional) pointer to 32 bytes of randomness
138 *
139 * Constant time in seckey and auxrnd32, but not in the resulting public key.
140 *
141 * It is recommended that auxrnd32 contains 32 uniformly random bytes, though
142 * it is optional (and does result in encodings that are indistinguishable from
143 * uniform even without any auxrnd32). It differs from the (mandatory) rnd32
144 * argument to secp256k1_ellswift_encode in this regard.
145 *
146 * This function can be used instead of calling secp256k1_ec_pubkey_create
147 * followed by secp256k1_ellswift_encode. It is safer, as it uses the secret
148 * key as entropy for the encoding (supplemented with auxrnd32, if provided).
149 *
150 * Like secp256k1_ellswift_encode, this function does not guarantee that the
151 * computed encoding is stable across versions of the library, even if all
152 * arguments (including auxrnd32) are the same.
153 */
154SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ellswift_create(
155    const secp256k1_context *ctx,
156    unsigned char *ell64,
157    const unsigned char *seckey32,
158    const unsigned char *auxrnd32
159) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
160
161/** Given a private key, and ElligatorSwift public keys sent in both directions,
162 *  compute a shared secret using x-only Elliptic Curve Diffie-Hellman (ECDH).
163 *
164 *  Returns: 1: shared secret was successfully computed
165 *           0: secret was invalid or hashfp returned 0
166 *  Args:    ctx:       pointer to a context object.
167 *  Out:     output:    pointer to an array to be filled by hashfp.
168 *  In:      ell_a64:   pointer to the 64-byte encoded public key of party A
169 *                      (will not be NULL)
170 *           ell_b64:   pointer to the 64-byte encoded public key of party B
171 *                      (will not be NULL)
172 *           seckey32:  pointer to our 32-byte secret key
173 *           party:     boolean indicating which party we are: zero if we are
174 *                      party A, non-zero if we are party B. seckey32 must be
175 *                      the private key corresponding to that party's ell_?64.
176 *                      This correspondence is not checked.
177 *           hashfp:    pointer to a hash function.
178 *           data:      arbitrary data pointer passed through to hashfp.
179 *
180 * Constant time in seckey32.
181 *
182 * This function is more efficient than decoding the public keys, and performing
183 * ECDH on them.
184 */
185SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ellswift_xdh(
186  const secp256k1_context *ctx,
187  unsigned char *output,
188  const unsigned char *ell_a64,
189  const unsigned char *ell_b64,
190  const unsigned char *seckey32,
191  int party,
192  secp256k1_ellswift_xdh_hash_function hashfp,
193  void *data
194) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3) SECP256K1_ARG_NONNULL(4) SECP256K1_ARG_NONNULL(5) SECP256K1_ARG_NONNULL(7);
195
196#ifdef __cplusplus
197}
198#endif
199
200#endif /* SECP256K1_ELLSWIFT_H */
201

src/wallet/receive.cpp

src/wallet/coinselection.cpp

src/consensus/validation.h

src/primitives/transaction.cpp

src/script/descriptor.cpp

src/bitcoin-cli.cpp

src/rpc/blockchain.cpp

src/rpc/rawtransaction.cpp

src/init.cpp

src/crypto/sha256.cpp

src/consensus/merkle.h

src/consensus/tx_check.h

src/consensus/tx_verify.h

src/policy/feerate.h

src/policy/feerate.cpp

src/primitives/transaction_identifier.h

src/chainparamsbase.h

src/chainparamsbase.cpp

src/util/moneystr.cpp

src/crypto/ripemd160.h

src/crypto/sha1.h

src/crypto/sha512.h

src/crypto/hmac_sha256.h

src/crypto/hmac_sha512.h

src/crypto/hmac_sha256.cpp

src/crypto/hmac_sha512.cpp

src/crypto/hkdf_sha256_32.h

src/crypto/hkdf_sha256_32.cpp

src/support/cleanse.h

src/support/cleanse.cpp

src/crypto/siphash.cpp

src/crypto/muhash.h

src/crypto/chacha20.h

src/crypto/poly1305.h

src/crypto/chacha20poly1305.h

src/crypto/chacha20poly1305.cpp

src/util/chaintype.cpp

src/util/obfuscation.h

src/util/byte_units.h

src/util/overflow.h

src/blockencodings.cpp

src/net_permissions.cpp

src/policy/packages.cpp

src/policy/rbf.cpp

src/policy/truc_policy.cpp

src/policy/ephemeral_policy.cpp

src/policy/settings.cpp

src/policy/policy.cpp

src/node/transaction.cpp

src/node/coin.cpp

src/rpc/client.cpp

src/rpc/external_signer.cpp

src/rpc/request.cpp

src/rpc/server_util.cpp

src/rpc/fees.cpp

src/rpc/output_script.cpp

src/rpc/rawtransaction_util.cpp

src/rpc/rawtransaction_util.h

src/rpc/register.h

src/rpc/request.h

src/rpc/server_util.h

src/rpc/protocol.h

src/rpc/server.h

src/rpc/signmessage.cpp

src/rpc/txoutproof.cpp

src/rpc/util.cpp

src/rpc/util.h

src/wallet/rpc/addresses.cpp

src/wallet/rpc/backup.cpp

src/wallet/rpc/coins.cpp

src/wallet/rpc/encrypt.cpp

src/wallet/rpc/signmessage.cpp

src/wallet/rpc/util.cpp

src/wallet/rpc/util.h

src/wallet/coincontrol.cpp

src/wallet/coincontrol.h

src/wallet/context.cpp

src/wallet/context.h

src/wallet/crypter.cpp

src/wallet/crypter.h

src/wallet/db.cpp

src/wallet/export.cpp

src/wallet/external_signer_scriptpubkeyman.cpp

src/wallet/rpc/spend.cpp

src/wallet/rpc/transactions.cpp

src/wallet/rpc/wallet.cpp

src/wallet/feebumper.cpp

src/wallet/feebumper.h

src/index/base.h

src/index/base.cpp

src/index/txindex.h

src/index/txindex.cpp

src/index/txindex_key.h

src/index/txospenderindex.h

src/index/txospenderindex.cpp

src/index/blockfilterindex.h

src/index/blockfilterindex.cpp

src/index/coinstatsindex.h

src/index/coinstatsindex.cpp

src/index/db_key.h

src/index/disktxpos.h

src/kernel/chain.cpp

src/kernel/chain.h

src/kernel/checks.cpp

src/kernel/checks.h

src/kernel/context.cpp

src/kernel/context.h

src/kernel/cs_main.cpp

src/kernel/cs_main.h

src/kernel/disconnected_transactions.cpp

src/kernel/disconnected_transactions.h

src/kernel/mempool_removal_reason.cpp

src/kernel/mempool_removal_reason.h

src/kernel/coinstats.cpp

src/kernel/coinstats.h

src/kernel/chainparams.cpp

src/kernel/chainparams.h

src/wallet/sqlite.cpp

src/wallet/sqlite.h

src/wallet/transaction.cpp

src/wallet/transaction.h

src/wallet/dump.cpp

src/wallet/dump.h

src/wallet/init.cpp

src/wallet/walletutil.cpp

src/wallet/walletutil.h

src/wallet/wallettool.cpp

src/wallet/wallettool.h

src/wallet/export.h

src/wallet/migrate.cpp

src/wallet/migrate.h

src/wallet/db.h

src/wallet/walletdb.cpp

src/wallet/interfaces.cpp

src/wallet/scriptpubkeyman.cpp

src/wallet/scriptpubkeyman.h

src/kernel/bitcoinkernel.cpp

src/kernel/bitcoinkernel.h

src/kernel/bitcoinkernel_wrapper.h

src/node/chainstate.cpp

src/node/chainstate.h

src/node/blockstorage.cpp

src/node/blockstorage.h

src/node/mempool_persist.cpp

src/node/mempool_persist.h

src/node/utxo_snapshot.cpp

src/node/utxo_snapshot.h

src/node/kernel_notifications.cpp

src/node/kernel_notifications.h

src/node/blockmanager_args.cpp

src/kernel/blockmanager_opts.h

src/util/expected.cpp

src/policy/settings.h

src/util/types.h

src/kernel/messagestartchars.h

src/kernel/warning.h

src/util/exception.h

src/common/license_info.h

src/node/coins_view_args.h

src/node/database_args.h

src/util/batchpriority.h

src/util/ui_change_type.h

src/node/coins_view_args.cpp

src/node/peerman_args.h

src/util/serfloat.h

src/node/blockmanager_args.h

src/node/database_args.cpp

src/util/overloaded.h

src/interfaces/types.h

src/node/chainstatemanager_args.h

src/node/minisketchwrapper.h

src/util/macros.h

src/util/syserror.h

src/common/run_command.h

src/util/bytevectorhash.cpp

src/node/mempool_persist_args.cpp

src/util/exec.h

src/util/rbf.h

src/crypto/hex_base.h

src/node/mempool_persist_args.h

src/interfaces/echo.h

src/util/any.h

src/util/batchpriority.cpp

src/util/threadnames.h

src/node/coin.h

src/node/mempool_args.h

src/util/asmap.h

src/util/bytevectorhash.h

src/node/context.cpp

src/util/insert.h

src/util/readwritefile.h

src/node/peerman_args.cpp

src/node/interface_ui.cpp

src/interfaces/handler.h

src/node/mining_args.h

src/util/hasher.cpp

src/common/init.h

src/kernel/mempool_limits.h

src/common/system.h

src/crypto/sha3.h

src/util/threadinterrupt.cpp

src/node/protocol_version.h

src/util/exception.cpp

src/common/messages.h

src/node/connection_types.cpp

src/util/bip32.h

src/common/license_info.cpp

src/util/stdmutex.h

src/common/run_command.cpp

src/util/check.cpp

src/util/golombrice.h

src/node/types.h

src/node/timeoffsets.h

src/util/readwritefile.cpp

src/util/fastrange.h

src/util/signalinterrupt.h

src/util/task_runner.h

src/util/syserror.cpp

src/common/interfaces.cpp

src/common/types.h

src/util/threadinterrupt.h

src/kernel/chainstatemanager_opts.h

src/node/psbt.h

src/policy/ephemeral_policy.h

src/util/trace.h

src/common/url.cpp

src/kernel/mempool_options.h

src/util/serfloat.cpp

src/kernel/notifications_interface.h

src/node/timeoffsets.cpp

src/node/warnings.cpp

src/util/hash_type.h

src/crypto/hex_base.cpp

src/node/eviction.h

src/util/tokenbucket.h

src/crypto/aes.h

src/common/pcp.h

src/util/feefrac.cpp

src/node/transaction.h

src/util/threadnames.cpp

src/common/signmessage.h

src/util/exec.cpp

src/util/signalinterrupt.cpp

src/clientversion.cpp

src/common/signmessage.cpp

src/compat/assumptions.h

src/compat/byteswap.h

src/deploymentinfo.cpp

src/deploymentinfo.h

src/deploymentstatus.cpp

src/deploymentstatus.h

src/dummywallet.cpp

src/external_signer.h

src/init/bitcoin-gui.cpp

src/init/bitcoin-node.cpp

src/init/bitcoin-qt.cpp

src/init/bitcoin-wallet.cpp

src/init/bitcoind.cpp

src/init/common.h

src/interfaces/init.h

src/interfaces/ipc.h

src/key_io.h

src/logging/categories.h

src/logging/timer.h

src/mapport.h

src/musig.h

src/net_permissions.h

src/netgroup.h

src/netmessagemaker.h

src/node/chainstatemanager_args.cpp

src/node/connection_types.h

src/node/context.h

src/node/interface_ui.h

src/node/mempool_args.cpp

src/node/mining_args.cpp

src/node/minisketchwrapper.cpp

src/node/txreconciliation.h

src/policy/fees/estimator_args.cpp

src/policy/fees/estimator_args.h

src/policy/fees/estimator_man.cpp

src/policy/fees/estimator_man.h

src/policy/packages.h

src/policy/rbf.h

src/policy/truc_policy.h

src/pow.h

src/primitives/block.cpp

src/randomenv.h

src/rest.h

src/script/keyorigin.h

src/script/parsing.cpp

src/script/parsing.h

src/script/script_error.h

src/script/sigcache.cpp

src/script/sigcache.h

src/script/solver.h

src/script/verify_flags.h

src/semaphore_grant.h

src/signet.h

src/span.h

src/support/allocators/secure.h

src/support/allocators/zeroafterfree.h

src/util/tokenpipe.cpp

src/util/translation.h

src/util/vector.h

src/versionbits.h

src/versionbits_impl.h

src/wallet/external_signer_scriptpubkeyman.h

src/wallet/fees.h

src/wallet/load.h

src/wallet/receive.h

src/wallet/rpc/wallet.h

src/wallet/types.h

src/walletinitinterface.h

src/zmq/zmqabstractnotifier.cpp

Independent explanations by MyBitcoinExplorer. Not affiliated with or endorsed by Bitcoin Core. Guides are educational and do not replace the source or its tests.

Bitcoin Core source © its contributors, distributed under the MIT license. Original notices and bundled third-party licenses are retained in the source tree.