iBTC Network
Starknet Contracts

Covered the Cairo contracts minting and burning iBTC on Starknet against Bitcoin deposits confirmed via Discrete Log Contracts.
report id
0502
category
Cross-chain & Bridges
language
Cairo
final report
June 2, 2025
lines of code
1122
Content

Download audit report

1

Executive Summary

This document presents the security review performed by Nethermind Security for iBTC Network's cairo contract. iBTC offers a bridgeless wrapped Bitcoin for decentralized finance by securing BTC directly in the Bitcoin Layer 1 using a 2-of-2 multisig vault system. iBTC uses Discrete Log Contracts (DLCs) on the Bitcoin network that enable conditional move and lock of Bitcoin.

Using Discrete Log Contracts (DLCs), the iBTC Network mints iBTC token that represents Bitcoin locked in the DLCs and burns the iBTC token when the DLC is settled.

The audit focused on the iBTC Cairo contracts, consisting of 1,122 lines of Cairo code, which enable minting and burning of the iBTC token on the Starknet blockchain once Bitcoin deposits are confirmed on Bitcoin Layer 1. The audit was performed using (a) manual analysis of the codebase, (b) automated analysis tools, and (c) creation of test cases.

Audit assessment
Audit TypeSecurity Review
Final ReportJune 2, 2025
Repositoryibtc-cairo
Commitf50901f
Final Commit3434907
DocumentationiBTC documentation
Documentation AssessmentMedium
Test Suite AssessmentMedium
Total findings
7
Fixed
7
Acknowledged
0
Mitigated
0
Unresolved
0

Findings by severity

  • Critical0
  • High1
  • Medium0
  • Low0
  • Informational4
  • Best Practices2

2

Audited Files

#ContractLoCCommentsRatioBlankTotal
1src/utils.cairo7667%1193
2src/ibtc_token.cairo1053129%24160
3src/interface.cairo1072523%20152
4src/ibtc_manager.cairo6528613%111849
5src/ibtc_library.cairo6334%470
6src/lib.cairo900%110
7src/timelock_controller.cairo311341%549
8src/event.cairo792126%21121
Total112218516.5%1971504

4

System Overview

The iBTC cairo contracts provide a mechanism for merchants to receive iBTC on Starknet in a 1:1 ratio once their BTC deposit has been attested and confirmed by Attestors using Flexible Round-Optimized Schnorr Threshold Signatures (FROST) on Bitcoin Layer 1. Merchants are entities such as trading firms, asset managers, and market makers who provide liquidity.

4.1 Vault Creation

Merchants set up an iBTCVault on Starknet that contains the necessary information to mint and burn iBTC. Every vault is identified by a unique identifier uuid and contains information such as the amount of BTC locked and iBTC minted, plus additional information including the status of the vault, the creator of the vault, and fee-related information.

    pub struct IBTCVault {
uuid: u256,
protocol_contract: ContractAddress,
timestamp: u64,
value_locked: u256,
creator: ContractAddress,
status: u8,
funding_tx_id: u256,
closing_tx_id: u256,
btc_fee_recipient: ByteArray,
btc_mint_fee_basis_points: u64,
btc_redeem_fee_basis_points: u64,
taproot_pubkey: ByteArray,
value_minted: u256,
wd_tx_id: u256,
}

4.2 Deposit Flow

Once BTC deposit on Bitcoin Layer 1 has been attested and confirmed, Approved signers will call set_status_pending (...), which will perform vault validation checks and update the status of the vault to AUC_STATE_1. After six block confirmations, the Approved signers will call the set_status_funded (...) function, which will mint iBTC to the iBTC Vault Creator after performing further vault validations.

Diagram from the audit report

4.3 Withdraw Flow

User can redeem their BTC through merchants with vault in Funded Status who can then execute the withdraw (...) function on the iBTCManager contract, which will effectively burn the iBTC token on Starknet. Attestors will then confirm and attest to the burn action. Approved signers will then call set_status_pending (...), wait for 6 block confirmation and then call set_status_funded (...) on the iBTCManager contract. The locked BTC will eventually be released, and the redemption will be completed in 30-60 minutes.

5

Risk Rating Methodology

The risk rating methodology used by Nethermind Security follows the principles established by the OWASP Foundation. The severity of each finding is determined by two factors: Likelihood and Impact.

Likelihood measures how likely the finding is to be uncovered and exploited by an attacker. This factor will be one of the following values:

  1. High: the issue is trivial to exploit and has no specific conditions that need to be met;
  2. Medium: the issue is moderately complex and may have some conditions that need to be met;
  3. Low: the issue is very complex and requires very specific conditions to be met.

When defining the likelihood of a finding, other factors are also considered. These can include but are not limited to motive, opportunity, exploit accessibility, ease of discovery, and ease of exploit.

Impact is a measure of the damage that may be caused if an attacker exploits the finding. This factor will be one of the following values:

  1. High: the issue can cause significant damage, such as loss of funds or the protocol entering an unrecoverable state;
  2. Medium: the issue can cause moderate damage, such as impacts that only affect a small group of users or only a particular part of the protocol;
  3. Low: the issue can cause little to no damage, such as bugs that are easily recoverable or cause unexpected interactions that cause minor inconveniences.

When defining the impact of a finding, other factors are also considered. These can include but are not limited to data and state integrity, loss of availability, financial loss, and reputation damage. After defining the likelihood and impact of an issue, the severity is determined according to the table below.

Impact / LikelihoodLowMediumHigh
HighMediumHighCritical
MediumLowMediumHigh
LowInfo / Best PracticesLowMedium
UndeterminedUndeterminedUndeterminedUndetermined

To address issues that do not fit a High, Medium or Low severity, Nethermind Security also uses three more finding severities: Informational, Best Practices, and Undetermined.

  1. Informational findings do not pose any risk to the application, but they carry some information that the audit team intends to pass to the client formally;
  2. Best Practice findings are used when some piece of code does not conform with smart contract development best practices;
  3. Undetermined findings are used when we cannot predict the impact or likelihood of the issue.

6

Issues

6.1 Potential for double minting via multiple signature sets

FileFix commitTypeStatus
ibtc_manager.cairoPR #6HighFixed

When a user deposits on the Bitcoin chain, an approved signer needs to call set_status_pending(...), and after some block confirmations, they'll need to call set_status_funded(...). Both of these functions take signatures of attestors as arguments. These signatures are validated using _attestor_multisig_is_valid(...). It ensures that the number of signatures is greater than or equal to threshold and signatures from the same attestors are not included more than once.

fn _attestor_multisig_is_valid(
ref self: ContractState,
uuid: u256,
btc_tx_id: u256,
tx_type: felt252,
amount: u256,
signatures: Span<(ContractAddress, Array<felt252>)>
) {
let threshold = self.threshold.read();
assert(signatures.len() >= threshold.into(), Errors::NOT_ENOUGH_SIGNATURES);
for (attestor, signature) in signatures {
// ...
let is_valid_signature = IAccountDispatcher { contract_address: *attestor }
.is_valid_signature(message, signature.clone());
assert(is_valid_signature == 'VALID', Errors::INVALID_SIGNATURE);
assert(self.accesscontrol.has_role(APPROVED_SIGNER, *attestor), Errors::INVALID_SIGNER);
self._check_signer_unique(*attestor, message);
}
}

fn _check_signer_unique(
ref self: ContractState,
attestor_pub_key: ContractAddress,
message_hash: felt252,
) {
assert(!self.seen_signers.read((attestor_pub_key, message_hash)), Errors::DUPLICATE_SIGNATURE);
self.seen_signers.write((attestor_pub_key, message_hash), true);
}

However, if there are more attestors than threshold, then a malicious approved signer can execute set_status_pending(...) and set_status_funded(...) more than once by passing different sets of signatures that are at least equal to the threshold.

For example, if threshold is 3 and there are 6 attestors, then a malicious approved signer can execute set_status_pending(...) and set_status_funded(...) via signatures from exactly 3 attestors and then execute both of these again after withdrawing via signatures from 3 different attestors.

Recommendation

Consider adding more checks to ensure that a user's deposit can't be processed more than once. This can be done by adding more validation to the Bitcoin transaction ID.

6.2 The ATTESTOR_MULTISIG_STRUCT_TYPE_HASH includes the u256 struct

FileFix commitTypeStatus
utils.cairoPR #6InfoFixed

The hash of struct like StarknetDomain, AttestorMultisigTx and u256 is calculated using selector macro.

struct StarknetDomain {
name: felt252,
version: felt252,
chain_id: felt252,
revision: felt252,
}
const STARKNET_DOMAIN_TYPE_HASH: felt252 =
selector!(
"\"StarknetDomain\"(\"name\":\"shortstring\",\"version\":\"shortstring\",\"chainId\":\"shortstring\",
\"revision\":\"shortstring\")"
);

pub struct AttestorMultisigTx {
uuid: u256,
btc_tx_id: u256,
tx_type: felt252,
amount: u256,
}
// @audit it also contains fields of u256
const ATTESTOR_MULTISIG_STRUCT_TYPE_HASH: felt252 =
selector!("\"AttestorMultisigTx\"(\"uuid\":\"u256\",\"btc_tx_id\":\"u256\",\"tx_type\":\"felt\",\"amount\":
\"u256\")\"u256\"(\"low\":\"u128\",\"high\":\"u128\")");


const U256_TYPE_HASH: felt252 = selector!("\"u256\"(\"low\":\"u128\",\"high\":\"u128\")");

However, the ATTESTOR_MULTISIG_STRUCT_TYPE_HASH incorrectly contains a u256 struct at the end.

Recommendation

Consider removing the u256 struct in the hash of the AttestorMultisigTx struct.

6.3 The ibtc_manager does not have a function to upgrade ibtc_token contract

FileFix commitTypeStatus
ibtc_token.cairoPR #6InfoFixed

The ibtc_token contract has an upgrade(...) function that can only be executed by the owner. The owner for the ibtc_token contract is the ibtc_manager. However, there's no function in the ibtc_manager contract to execute upgrade(...) in the ibtc_token contract.

Although transfer_token_contract_ownership(...) can be used to transfer ownership, the new owner can then execute upgrade(...) in the ibtc_token contract.

Recommendation

Consider adding a function in the ibtc_manager contract to execute upgrade(...) in the ibtc_token contract.

6.4 The set_approved_signers(...) override signer_count rather than increasing it

FileFix commitTypeStatus
ibtc_manager.cairoPR #6
PR #6
InfoFixed

When an account is granted APPROVED_SIGNER role via grant_role(...), the signer_count is increase by 1.

fn grant_role(ref self: ContractState, role: felt252, account: ContractAddress) {
if (self._has_any_roles(account)) {
panic_with_felt252(Errors::INCOMPATIBLE_ROLE);
}
self.accesscontrol.grant_role(role, account);
if (role == APPROVED_SIGNER) {
self.signer_count.write(self.signer_count.read() + 1);
}
}

However, an account can be granted the APPROVED_SIGNER role using set_approved_signers(...), too. However, this doesn't increase the signer_count but rather overrides it.

fn set_approved_signers(ref self: ContractState, signers: Array<ContractAddress>) {
self.accesscontrol.assert_only_role(IBTC_ADMIN_ROLE);

let signers_len = signers.len();
let mut i: usize = 0;
loop {
if i >= signers_len {
break;
}
let signer = signers.at(i);
self.accesscontrol._grant_role(APPROVED_SIGNER, *signer);
i += 1;
};
// @audit signer_count is overriden
self.signer_count.write(signers_len.try_into().unwrap());
self.emit(SetApprovedSigners{signers});
}

If set_approved_signers(...) is ever used after executing grant_role(...) to grant an account the APPROVED_SIGNER role, the signer_count would have incorrect accounting.

Recommendation

Consider increasing signer_count rather than overriding it in set_approved_signers(...).

Update from Nethermind Security

The set_approved_signers(...) can only be executed by IBTC_ADMIN_ROLE. Previously, it was directly using _grant_role(...) which doesn't have any access control so the caller of set_approved_signers(...) needs to have IBTC_ADMIN_ROLE only. However, now, it further invokes grant_role(...) which can only be executed by admin of that role i.e. admin of APPROVED_SIGNER role i.e. DEFAULT_ADMIN_ROLE. So the caller not only needs to have IBTC_ADMIN_ROLE but also DEFAULT_ADMIN_ROLE.

6.5 The set_status_funded(...) can be executed for a different transaction ID than that of set_status_pending(...)

FileFix commitTypeStatus
ibtc_manager.cairoPR #6InfoFixed

When a user deposits on the Bitcoin chain, an approved signer needs to call set_status_pending(...), and after some block confirmations, they'll need to call set_status_funded(...). Both of these functions take a transaction ID as an argument. The transaction ID is expected to be the same in both cases. However, the code doesn't ensure that the transaction ID passed as an argument in set_status_funded(...) is the same as the one passed in set_status_pending(...).

Recommendation

Consider adding a check to ensure that the transaction ID passed in set_status_funded(...) is the same as the one passed in set_status_pending(...).

6.6 The _check_por(...) does not need to return bool

FileFix commitTypeStatus
ibtc_manager.cairoPR #6
PR #6
Best PracticesFixed

The _check_por(...) is not completely implemented yet, but it's expected to either always return true or revert. If it returns false, then the iBTC won't be minted to the user for their deposits, and their deposit on the Bitcoin chain would be stuck. So, it should revert rather than return false, as also done in the Solidity implementation. As the function will never return false, there's no need to return a boolean.

Recommendation

Consider updating the function signature for _check_por(...).

Update from Nethermind Security

The _check_mint(...) is also modified and now it doesn't return the bool which completely defeats its purpose. It was previously used in if check to ensure that tokens are only minted if it returns true, whereas now as it doesn't return a bool it's executed and not used in if check and tokens are minted irrespectively. Thus, now executing _check_mint(...) does nothing.

6.7 The get_ssf_message(...) and get_ssp_message(...) takes mutable reference of the contract state

FileFix commitTypeStatus
ibtc_manager.cairoPR #6Best PracticesFixed

The get_ssf_message(...) and get_ssp_message(...) functions return the hash of the message that can be used by attestors to sign the message. It doesn't update the contract state but just returns the calculated hash.

#[external(v0)]
fn get_ssf_message(ref self: ContractState, attestor: ContractAddress, uuid: u256, btc_tx_id: u256, new_value_locked: u256) -> felt252 {
let message = AttestorMultisigTx {
uuid,
btc_tx_id,
tx_type: 'set-status-funded',
amount: new_value_locked,
};

message.get_message_hash(attestor)
}

#[external(v0)]
fn get_ssp_message(ref self: ContractState, attestor: ContractAddress, uuid: u256, wdtx_id: u256, new_value_locked: u256) -> felt252 {
let message = AttestorMultisigTx {
uuid,
btc_tx_id: wdtx_id,
tx_type: 'set-status-pending',
amount: new_value_locked,
};

let message_hash = message.get_message_hash(attestor);
message_hash
}

However, both functions take a mutable reference of self, i.e, the contract state.

Recommendation

Consider taking a snapshot of the contract state ( self: @ContractState) rather than a mutable reference ( ref self: ContractState).

7

Documentation Evaluation

Software documentation refers to the written or visual information that describes the functionality, architecture, design, and implementation of software. It provides a comprehensive overview of the software system and helps users, developers, and stakeholders understand how the software works, how to use it, and how to maintain it. Software documentation can take different forms, such as user manuals, system manuals, technical specifications, requirements documents, design documents, and code comments. Software documentation is critical in software development, enabling effective communication between developers, testers, users, and other stakeholders. It helps to ensure that everyone involved in the development process has a shared understanding of the software system and its functionality. Moreover, software documentation can improve software maintenance by providing a clear and complete understanding of the software system, making it easier for developers to maintain, modify, and update the software over time. Smart contracts can use various types of software documentation. Some of the most common types include:

  • Technical whitepaper: A technical whitepaper is a comprehensive document describing the smart contract’s design and technical details. It includes information about the purpose of the contract, its architecture, its components, and how they interact with each other;
  • User manual: A user manual is a document that provides information about how to use the smart contract. It includes step-by-step instructions on how to perform various tasks and explains the different features and functionalities of the contract;
  • Code documentation: Code documentation is a document that provides details about the code of the smart contract. It includes information about the functions, variables, and classes used in the code, as well as explanations of how they work;
  • API documentation: API documentation is a document that provides information about the API (Application Programming Interface) of the smart contract. It includes details about the methods, parameters, and responses that can be used to interact with the contract;
  • Testing documentation: Testing documentation is a document that provides information about how the smart contract was tested. It includes details about the test cases that were used, the results of the tests, and any issues that were identified during testing;
  • Audit documentation: Audit documentation includes reports, notes, and other materials related to the security audit of the smart contract. This type of documentation is critical in ensuring that the smart contract is secure and free from vulnerabilities.

These types of documentation are essential for smart contract development and maintenance. They help ensure that the contract is properly designed, implemented, and tested, and they provide a reference for developers who need to modify or maintain the contract in the future.

8

Remarks & Test Suite

The iBTC team has provided a comprehensive walkthrough of the project in the kick-off call. The documentation includes the explanation of the intended functionalities. Moreover, the team addressed the questions and concerns raised by the Nethermind Security team, providing valuable insights and a comprehensive understanding of the project's technical aspects.

As auditors, we recommend that any changes or updates made to the audited codebase undergo a re-audit or security review to address potential vulnerabilities or risks introduced by the modifications. By conducting a re-audit or security review of the modified codebase, you can significantly enhance the overall security of your system and reduce the likelihood of exploitation. However, we do not possess the authority or right to impose obligations or restrictions on our clients regarding codebase updates, modifications, or subsequent audits. Accordingly, the decision to seek a re-audit or security review lies solely with you.

This report is based on the scope of materials and documentation provided by you to Nethermind in order that Nethermind could conduct the security review outlined in 1. Executive Summary and 2. Audited Files. The results set out in this report may not be complete nor inclusive of all vulnerabilities. Nethermind has provided the review and this report on an as-is, where-is, and as-available basis. You agree that your access and/or use, including but not limited to any associated services, products, protocols, platforms, content, and materials, will be at your sole risk. Blockchain technology remains under development and is subject to unknown risks and flaws. The review does not extend to the compiler layer, or any other areas beyond the programming language, or other programming aspects that could present security risks. This report does not indicate the endorsement of any particular project or team, nor guarantee its security. No third party should rely on this report in any way, including for the purpose of making any decisions to buy or sell a product, service or any other asset. To the fullest extent permitted by law, Nethermind disclaims any liability in connection with this report, its content, and any related services and products and your use thereof, including, without limitation, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement. Nethermind does not warrant, endorse, guarantee, or assume responsibility for any product or service advertised or offered by a third party through the product, any open source or third-party software, code, libraries, materials, or information linked to, called by, referenced by or accessible through the report, its content, and the related services and products, any hyperlinked websites, any websites or mobile applications appearing on any advertising, and Nethermind will not be a party to or in any way be responsible for monitoring any transaction between you and any third-party providers of products or services. As with the purchase or use of a product or service through any medium or in any environment, you should use your best judgment and exercise caution where appropriate. FOR AVOIDANCE OF DOUBT, THE REPORT, ITS CONTENT, ACCESS, AND/OR USAGE THEREOF, INCLUDING ANY ASSOCIATED SERVICES OR MATERIALS, SHALL NOT BE CONSIDERED OR RELIED UPON AS ANY FORM OF FINANCIAL, INVESTMENT, TAX, LEGAL, REGULATORY, OR OTHER ADVICE.