Skip to content

Bitcoin Policy Engine Documentation #436

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Oct 14, 2025
Merged

Bitcoin Policy Engine Documentation #436

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ecabbc0
bitcoin policy engine docuemntation
omkarshanbhag Oct 5, 2025
4d28fd8
add bitcoin policy examples to doc structure
omkarshanbhag Oct 5, 2025
4d843da
fix links, add bitcoin tx locktime to policy language
omkarshanbhag Oct 5, 2025
a54a1d0
pr comments
omkarshanbhag Oct 6, 2025
daafae7
extra context on btc signing
omkarshanbhag Oct 9, 2025
4403d7b
Update concepts/policies/examples/bitcoin.mdx
omkarshanbhag Oct 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions concepts/policies/examples/bitcoin.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
title: "Bitcoin"
description: "This page provides examples of policies governing signing."
sidebarTitle: "Bitcoin"
---

Note: see the [language section](/concepts/policies/language#bitcoin) for more details. For context on bitcoin transaction reinsertion, see the [bitcoin network support](/networks/bitcoin) page


#### Allow signing Bitcoin transactions ONLY if all outputs are being sent to a certain address

```json
{
"policyName": "Enable bitcoin transactions to be sent to <BITCOIN_ADDRESS>",
"effect": "EFFECT_ALLOW",
"condition": "bitcoin.tx.outputs.all(o, o.address == <BITCOIN_ADDRESS>)"
}
```

#### Allow signing Bitcoin transactions restricting output values

```json
{
"policyName": "Allow signing bitcoin transactions only if all outputs have value < 200000 satoshis",
"effect": "EFFECT_ALLOW",
"condition": "bitcoin.tx.outputs.all(o, o.value < 200000)"
}
```

#### Allow signing Bitcoin transactions only if ALL inputs are spending a particular UTXO (this key is only allowed to spend one input)

```json
{
"policyName": "Only allow spending of a single bitcoin transaction input",
"effect": "EFFECT_ALLOW",
"condition": "bitcoin.tx.inputs.all(i, i.tx_id == <TX_ID_OF_UTXO> && i.vout == <VOUT_OF_UTXO>)"
}
```
30 changes: 27 additions & 3 deletions concepts/policies/language.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ Keywords are reserved words that are dynamically interchanged for real values at
| **eth.eip_7702_authorization** | Eip7702Authorization | EIP-7702 Authorization (see Appendix below) |
| **solana.tx** | SolanaTransaction | The parsed Solana transaction payload (see Appendix below) |
| **tron.tx** | TronTransaction | The parsed Tron transaction payload (see Appendix below) |
| **bitcoin.tx** | BitcoinTransaction | The parsed Bitcoin transaction payload (see Appendix below) |
| **wallet** | Wallet | The target wallet used in sign requests |
| **private_key** | PrivateKey | The target private key used in sign requests |

Expand Down Expand Up @@ -109,9 +110,9 @@ The language is strongly typed which makes policies easy to author and maintain.
| **Eip712TypedData** | primary_type | string | The type of the primary (i.e. outermost) structure in the `message` JSON |
| | domain | Eip712Domain | The `Domain` of the payload |
| | message | Map\<string, Value\> | JSON serializaiton of the message payload |
| **Eip7702Authorization** | address | string | The address you would like to authorize |
| | chain_id | number | The EVM chain ID |
| | nonce | number | The nonce of the authority |
| **Eip7702Authorization** | address | string | The address you would like to authorize |
| | chain_id | number | The EVM chain ID |
| | nonce | number | The nonce of the authority |
| **SolanaTransaction** | account_keys | list\<string\> | The accounts (public keys) involved in the transaction |
| | program_keys | list\<string\> | The programs (public keys) involved in the transaction |
| | instructions | list\<Instruction\> | A list of Instructions (see below) |
Expand All @@ -126,6 +127,10 @@ The language is strongly typed which makes policies easy to author and maintain.
| | data | string | Transaction memo (not the call data!) |
| | fee_limit | int | The maximum energy cost allowed for the execution of smart contract transactions |
| | contract | list\<TronContract\> | A list of TronContract. This is the main content of a Tron transaction. This determines the type of transaction being executed and its parameters (see below) |
| **BitcoinTransaction** | version | string | The version of the Bitcoin transaction |
| | inputs | list\<BitcoinTxInput\> | All inputs to this Bitcoin transaction |
| | outputs | list\<BitcoinTxOutput\> | All outputs created by this Bitcoin transaction |
| | locktime | BitcoinTxLocktime | The locktime of this bitcoin transaction |

\*\*NOTE: The `ContractArgument` type, used in documentation for ABI an IDL arguments represents an enum indicating this type could be any one of the string, number, array or struct types listed in our Primitives section.

Expand Down Expand Up @@ -190,6 +195,15 @@ The language is strongly typed which makes policies easy to author and maintain.
| | keys | TronKey | A list of address's and weight's that jointly own the permission can be up to 5 keys. |
| **TronKey** | address | string | The address authorized for a specific TronPermission |
| | weight | int | The weight of this address's signature for this permission, used to reach "threshold" in a TronPermission |
| **BitcoinTxInput** | tx_id | string | The transaction id of the Bitcoin transaction that created the output that is being spent by this input |
| | vout | int | The index in the output array on the Bitcoin transaction that created the output being spent by this input |
| | sequence | int | The sequence field on this input which is set whether the transaction can be replaced or when it can be mined |
| **BitcoinTxOutput** | value | int | The value of this output in Satoshis |
| | script_pubkey | string | The locking code for this transaction output |
| | address | string | The on chain address representation for this transaction output |
| | address_type | string | The address derivation type of the address for this transaction output |
| **BitcoinTxLocktime** | amount | int | The amount represented in this transaction's locktime |
| | type | string | The type of locktime represented (either 'Seconds' or 'Blocks') |

## Activity Breakdown

Expand Down Expand Up @@ -282,3 +296,13 @@ Our Tron policy language (accessible via `tron.tx`) allows for policy control ov
- TriggerSmartContract (Smart contract, including, but not limited to TRC-20, invocations)

See the [Tron policy examples](/concepts/policies/examples#tron) for sample scenarios.

### Bitcoin

Our Bitcoin policy language (accessible via `bitcoin.tx`) allows for policy control over signing Bitcoin transactions.

NOTE: While our `SIGN TRANSACTION` endpoint takes in a Partially Signed Bitcoin Transaction (PSBT) as required for signing context -- our policy language supports only the standard fields inside a Bitcoin transaction: https://learnmeabitcoin.com/technical/transaction/#structure

For further reference on how Turnkey handles Bitcoin transactions in our policy-enabled transaction signing flow, check out this section in our [Bitcoin Network Support](networks/bitcoin#policy-enabled-bitcoin-transaction-signing) page.

See the [Bitcoin policy examples](/concepts/policies/examples/bitcoin) for sample Bitcoin policies.
3 changes: 2 additions & 1 deletion docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -242,7 +242,8 @@
"concepts/policies/examples/signing-control",
"concepts/policies/examples/ethereum",
"concepts/policies/examples/solana",
"concepts/policies/examples/tron"
"concepts/policies/examples/tron",
"concepts/policies/examples/bitcoin"
]
},
"concepts/policies/delegated-access",
Expand Down
Loading