Inside Bitcoin

1251    - `-BEGIN VERIFY SCRIPT-`
1252    - `-END VERIFY SCRIPT-`
1253
1254The scripted-diff is verified by the tool `test/lint/commit-script-check.sh`. The tool's default behavior, when supplied
1255with a commit is to verify all scripted-diffs from the beginning of time up to said commit. Internally, the tool passes
1256the first supplied argument to `git rev-list --reverse` to determine which commits to verify script-diffs for, ignoring
1257commits that don't conform to the commit message format described above.
1258
1259For development, it might be more convenient to verify all scripted-diffs in a range `A..B`, for example:
1260
1261```bash
1262test/lint/commit-script-check.sh origin/master..HEAD
1263```
1264
1265### Suggestions and examples
1266
1267If you need to replace in multiple files, prefer `git ls-files` to `find` or globbing, and `git grep` to `grep`, to
1268avoid changing files that are not under version control.
1269
1270For efficient replacement scripts, reduce the selection to the files that potentially need to be modified, so for
1271example, instead of a blanket `git ls-files src | xargs sed -i s/apple/orange/`, use
1272`git grep -l apple src | xargs sed -i s/apple/orange/`.
1273
1274Also, it is good to keep the selection of files as specific as possible — for example, replace only in directories where
1275you expect replacements — because it reduces the risk that a rebase of your commit by re-running the script will
1276introduce accidental changes.
1277
1278Some good examples of scripted-diff:
1279
1280- [scripted-diff: Rename InitInterfaces to NodeContext](https://github.com/bitcoin/bitcoin/commit/301bd41a2e6765b185bd55f4c541f9e27aeea29d)
1281uses an elegant script to replace occurrences of multiple terms in all source files.
1282
1283- [scripted-diff: Remove g_connman, g_banman globals](https://github.com/bitcoin/bitcoin/commit/8922d7f6b751a3e6b3b9f6fb7961c442877fb65a)
1284replaces specific terms in a list of specific source files.
1285
1286- [scripted-diff: Replace fprintf with tfm::format](https://github.com/bitcoin/bitcoin/commit/fac03ec43a15ad547161e37e53ea82482cc508f9)
1287does a global replacement but excludes certain directories.
1288
1289To find all previous uses of scripted diffs in the repository, do:
1290
1291```
1292git log --grep="-BEGIN VERIFY SCRIPT-"
1293```
1294
1295## Release notes
1296
1297Release notes should be written for any PR that:
1298
1299- introduces a notable new feature
1300- fixes a significant bug
1301- changes an API or configuration model
1302- makes any other visible change to the end-user experience.
1303
1304Release notes should be added to a PR-specific release note file at
1305`/doc/release-notes-<PR number>.md` to avoid conflicts between multiple PRs.
1306All `release-notes*` files are merged into a single `release-notes-<version>.md` file prior to the release.
1307
1308## RPC interface guidelines
1309
1310A few guidelines for introducing and reviewing new RPC interfaces:
1311
1312- Method naming: use consecutive lower-case names such as `getrawtransaction` and `submitblock`.
1313
1314  - *Rationale*: Consistency with the existing interface.
1315
1316- Argument and field naming: please consider whether there is already a naming
1317  style or spelling convention in the API for the type of object in question
1318  (`blockhash`, for example), and if so, try to use that. If not, use snake case
1319  `fee_delta` (and not, e.g. `feedelta` or camel case `feeDelta`).
1320
1321  - *Rationale*: Consistency with the existing interface.
1322
1323- Use the JSON parser for parsing, don't manually parse integers or strings from
1324  arguments unless absolutely necessary.
1325
1326  - *Rationale*: Introduces hand-rolled string manipulation code at both the caller and callee sites,
1327    which is error-prone, and it is easy to get things such as escaping wrong.
1328    JSON already supports nested data structures, no need to re-invent the wheel.
1329
1330  - *Exception*: AmountFromValue can parse amounts as string. This was introduced because many JSON
1331    parsers and formatters hard-code handling decimal numbers as floating-point
1332    values, resulting in potential loss of precision. This is unacceptable for
1333    monetary values. **Always** use `AmountFromValue` and `ValueFromAmount` when
1334    inputting or outputting monetary values. The only exceptions to this are
1335    `prioritisetransaction` and `getblocktemplate` because their interface
1336    is specified as-is in BIP22.
1337
1338- Missing arguments and 'null' should be treated the same: as default values. If there is no
1339  default value, both cases should fail in the same way. The easiest way to follow this
1340  guideline is to detect unspecified arguments with `params[x].isNull()` instead of
1341  `params.size() <= x`. The former returns true if the argument is either null or missing,
1342  while the latter returns true if is missing, and false if it is null.
1343
1344  - *Rationale*: Avoids surprises when switching to name-based arguments. Missing name-based arguments
1345  are passed as 'null'.
1346
1347- Try not to overload methods on argument type. E.g. don't make `getblock(true)` and `getblock("hash")`
1348  do different things.
1349
1350  - *Rationale*: This is impossible to use with `bitcoin-cli`, and can be surprising to users.
1351
1352  - *Exception*: Some RPC calls can take both an `int` and `bool`, most notably when a bool was switched
1353    to a multi-value, or due to other historical reasons. **Always** have false map to 0 and
1354    true to 1 in this case.
1355
1356- For new RPC methods, if implementing a `verbosity` argument, use integer verbosity rather than boolean.
1357  Disallow usage of boolean verbosity (see `ParseVerbosity()` in [util.h](/src/rpc/util.h)).
1358
1359  - *Rationale*: Integer verbosity allows for multiple values. Undocumented boolean verbosity is deprecated
1360    and new RPC methods should prevent its use.
1361
1362- Add every non-string RPC argument `(method, idx, name)` to the table `vRPCConvertParams` in `rpc/client.cpp`.
1363
1364  - *Rationale*: `bitcoin-cli` and the GUI debug console use this table to determine how to
1365    convert a plaintext command line to JSON. If the types don't match, the method can be unusable
1366    from there.
1367
1368- A RPC method must either be a wallet method or a non-wallet method. Do not
1369  introduce new methods that differ in behavior based on the presence of a wallet.
1370
1371  - *Rationale*: As well as complicating the implementation and interfering
1372    with the introduction of multi-wallet, wallet and non-wallet code should be
1373    separated to avoid introducing circular dependencies between code units.
1374
1375- Try to make the RPC response a JSON object.
1376
1377  - *Rationale*: If a RPC response is not a JSON object, then it is harder to avoid API breakage if
1378    new data in the response is needed.
1379
1380- Wallet RPCs call BlockUntilSyncedToCurrentChain to maintain consistency with
1381  `getblockchaininfo`'s state immediately prior to the call's execution. Wallet
1382  RPCs whose behavior does *not* depend on the current chainstate may omit this
1383  call.
1384
1385  - *Rationale*: In previous versions of Bitcoin Core, the wallet was always
1386    in-sync with the chainstate (by virtue of them all being updated in the
1387    same cs_main lock). In order to maintain the behavior that wallet RPCs
1388    return results as of at least the highest best-known block an RPC
1389    client may be aware of prior to entering a wallet RPC call, we must block
1390    until the wallet is caught up to the chainstate as of the RPC call's entry.
1391    This also makes the API much easier for RPC clients to reason about.
1392
1393- Use *invalid* bech32 addresses (e.g. in the constant array `EXAMPLE_ADDRESS`) for
1394  `RPCExamples` help documentation.
1395
1396  - *Rationale*: Prevent accidental transactions by users and encourage the use
1397    of bech32 addresses by default.
1398
1399- Use the `UNIX_EPOCH_TIME` constant when describing UNIX epoch time or
1400  timestamps in the documentation.
1401
1402  - *Rationale*: User-facing consistency.
1403
1404- Use `fs::path::u8string()`/`fs::path::utf8string()` and `fs::u8path()` functions when converting path
1405  to JSON strings, not `fs::PathToString` and `fs::PathFromString`
1406
1407  - *Rationale*: JSON strings are Unicode strings, not byte strings, and
1408    RFC8259 requires JSON to be encoded as UTF-8.
1409
1410A few guidelines for modifying existing RPC interfaces:
1411
1412- It's preferable to avoid changing an RPC in a backward-incompatible manner, but in that case, add an associated `-deprecatedrpc=` option to retain previous RPC behavior during the deprecation period. Backward-incompatible changes include: data type changes (e.g. from `{"warnings":""}` to `{"warnings":[]}`, changing a value from a string to a number, etc.), logical meaning changes of a value, key name changes (e.g. `{"warning":""}` to `{"warnings":""}`), or removing a key from an object. Adding a key to an object is generally considered backward-compatible. Include a release note that refers the user to the RPC help for details of feature deprecation and re-enabling previous behavior. [Example RPC help](https://github.com/bitcoin/bitcoin/blob/94f0adcc/src/rpc/blockchain.cpp#L1316-L1323).
1413
1414  - *Rationale*: Changes in RPC JSON structure can break downstream application compatibility. Implementation of `deprecatedrpc` provides a grace period for downstream applications to migrate. Release notes provide notification to downstream users.
1415
1416## Feature deprecation and removal process
1417
1418Bitcoin Core uses a structured process for deprecating and removing features to give
1419downstream users and applications time to migrate.
1420
1421### General principles
1422
1423- The minimum deprecation **grace period** for a feature that is going to be removed is one
1424  major release.
1425- Any deprecation or removal must come with a release note.
1426
1427### RPC methods and fields
1428
1429- To deprecate an entire RPC method, gate the old behavior behind `-deprecatedrpc=<feature>`.
1430  Deprecated features should remain accessible via this flag during the grace period so
1431  downstream users are not immediately broken.
1432- The RPC help text must mention the deprecation and the `-deprecatedrpc=<feature>` flag
1433  that re-enables it. For example:
1434  ```
1435  "\nDeprecated in v25.0, use the `newfoo` RPC instead. Start bitcoind with"
1436  " `-deprecatedrpc=foo` to continue using this RPC.\n"
1437  ```
1438
1439### Startup options
1440
1441- To deprecate a startup option, emit a warning via `LogWarning` or `InitWarning` when the
1442  option is used, so users are notified at startup.
1443- Update the option's help text to indicate it is deprecated and, if applicable, will be
1444  removed in a future release.
1445
1446### REST interface
1447
1448- Deprecated REST endpoints or behaviors should be documented in `doc/REST-interface.md`
1449  with the version they were deprecated.
1450
1451### ZMQ
1452
1453- Deprecated ZMQ topics or behaviors should be documented in `doc/zmq.md` with the version
1454  they were deprecated.
1455
1456## Internal interface guidelines
1457
1458Internal interfaces between parts of the codebase that are meant to be
1459independent (node, wallet, GUI), are defined in
1460[`src/interfaces/`](../src/interfaces/). The main interface classes defined
1461there are [`interfaces::Chain`](../src/interfaces/chain.h), used by wallet to
1462access the node's latest chain state,
1463[`interfaces::Node`](../src/interfaces/node.h), used by the GUI to control the
1464node, [`interfaces::Wallet`](../src/interfaces/wallet.h), used by the GUI
1465to control an individual wallet and [`interfaces::Mining`](../src/interfaces/mining.h),
1466used by RPC to generate block templates. There are also more specialized interface
1467types like [`interfaces::Handler`](../src/interfaces/handler.h)
1468[`interfaces::ChainClient`](../src/interfaces/chain.h) passed to and from
1469various interface methods.
1470
1471Interface classes are written in a particular style so node, wallet, and GUI
1472code doesn't need to run in the same process, and so the class declarations
1473work more easily with tools and libraries supporting interprocess
1474communication:
1475
1476- Interface classes should be abstract and have methods that are [pure
1477  virtual](https://en.cppreference.com/w/cpp/language/abstract_class). This
1478  allows multiple implementations to inherit from the same interface class,
1479  particularly so one implementation can execute functionality in the local
1480  process, and other implementations can forward calls to remote processes.
1481
1482- Interface method definitions should wrap existing functionality instead of
1483  implementing new functionality. Any substantial new node or wallet
1484  functionality should be implemented in [`src/node/`](../src/node/) or
1485  [`src/wallet/`](../src/wallet/) and just exposed in
1486  [`src/interfaces/`](../src/interfaces/) instead of being implemented there,
1487  so it can be more modular and accessible to unit tests.
1488
1489- Interface method parameter and return types should either be serializable or
1490  be other interface classes. Interface methods shouldn't pass references to
1491  objects that can't be serialized or accessed from another process.
1492
1493  Examples:
1494
1495  ```c++
1496  // Good: takes string argument and returns interface class pointer
1497  virtual unique_ptr<interfaces::Wallet> loadWallet(std::string filename) = 0;
1498
1499  // Bad: returns CWallet reference that can't be used from another process
1500  virtual CWallet& loadWallet(std::string filename) = 0;