Skills
skills/btc-vision/opnet-skills/opnet

opnet

SKILL.md

OPNet Development Skill

Critical Architecture Facts

OPNet is a Bitcoin L1 consensus layer (not a metaprotocol) that enables smart contracts directly on Bitcoin using WebAssembly. It does not have a gas token; it uses bitcoin directly. Contracts are non-custodial: they never hold BTC, cannot receive blockchain.tx.value, and cannot send blockchain.transfer(). All financial logic follows a "verify, don't custody" pattern where the contract verifies the user's L1 transaction outputs against internal state.

OPNet does NOT use OP_RETURN. OPNet embeds transaction data in SegWit witness fields using P2WDA (Pay-to-Witness-Data-Authentication), which exploits the witness discount where witness bytes weigh 1 unit instead of 4. This makes OPNet data embedding ~75% cheaper than OP_RETURN. Some reference files discuss OP_RETURN in the context of raw Bitcoin script opcodes that contracts can construct, but that is a general Bitcoin scripting capability, not OPNet's data embedding mechanism. Never describe OPNet as using OP_RETURN for its consensus layer or transaction data.

Transactions containing BTC on OPNet can partially revert: only the consensus-layer execution reverts, while Bitcoin transfers remain valid since they are always valid when included in blocks. OPNet is fully trustless, permissionless, and decentralized, relying on Bitcoin PoW and OPNet epoch SHA-1 mining. After 20 blocks an epoch is buried deep enough that changing it requires rewriting Bitcoin's history at millions of dollars per hour. The checksum root for each epoch is a cryptographic fingerprint of the entire state; if even one bit differs, the checksum completely changes, making silent state corruption impossible.

Packages

Install specific versions for compatibility:

npm i @btc-vision/transaction@1.8.0-beta.9 opnet@1.8.1-beta.6 @btc-vision/ecpair@4.0.2 @btc-vision/bip32@7.0.2 @btc-vision/bitcoin@7.0.0-alpha.10

For smart contract development (AssemblyScript, compiles to WASM):

npm i @btc-vision/btc-runtime

TypeScript target must be ES2025. Node.js >= 22.0.0. All amounts are bigint.

Reference Documentation

Read the appropriate reference file(s) based on the task. All references are in references/ relative to this file. Every file is a 1:1 copy from official packages with nothing omitted.

MANDATORY: Read Before Writing Any Code

When Reference File
Writing or auditing ANY OPNet contract example-contracts.md — Complete production source code for OP20, OP721, stablecoin, pegged WBTC, multi-oracle stablecoin, BTC name resolver, package registry, all events, constants, asconfig.json, package.json
Writing ANY TypeScript code typescript-law.md — TypeScript Law 2026: strict type system, forbidden types, defensive programming, error handling, class design, async patterns, security, BigInt for financials

Runtime: Getting Started (@btc-vision/btc-runtime)

Topic Reference File
Runtime docs index runtime-README.md
Installation runtime-getting-started-installation.md
Project structure runtime-getting-started-project-structure.md
First contract runtime-getting-started-first-contract.md

Runtime: Core Concepts

Topic Reference File
Blockchain environment runtime-core-concepts-blockchain-environment.md
Storage system runtime-core-concepts-storage-system.md
Pointers runtime-core-concepts-pointers.md
Events runtime-core-concepts-events.md
Decorators runtime-core-concepts-decorators.md
Security runtime-core-concepts-security.md

Runtime: Contracts

Topic Reference File
OPNet base contract runtime-contracts-op-net-base.md
OP20 token contract runtime-contracts-op20-token.md
OP20S signatures contract runtime-contracts-op20s-signatures.md
OP721 NFT contract runtime-contracts-op721-nft.md
Reentrancy guard runtime-contracts-reentrancy-guard.md

Runtime: Storage

Topic Reference File
Stored primitives (StoredU256, StoredBoolean, etc.) runtime-storage-stored-primitives.md
Stored maps (AddressMap, StoredMap) runtime-storage-stored-maps.md
Stored arrays (StoredArray) runtime-storage-stored-arrays.md
Memory maps (MemoryMap) runtime-storage-memory-maps.md

Runtime: Types

Topic Reference File
Address type runtime-types-address.md
BytesWriter and BytesReader runtime-types-bytes-writer-reader.md
Calldata runtime-types-calldata.md
SafeMath runtime-types-safe-math.md

Runtime: API Reference

Topic Reference File
Blockchain API (tx, block, contract, environment) runtime-api-reference-blockchain.md
Events API runtime-api-reference-events.md
OP20 API runtime-api-reference-op20.md
OP721 API runtime-api-reference-op721.md
SafeMath API runtime-api-reference-safe-math.md
Storage API runtime-api-reference-storage.md

Runtime: Advanced

Topic Reference File
Bitcoin scripts runtime-advanced-bitcoin-scripts.md
Cross-contract calls runtime-advanced-cross-contract-calls.md
Plugins runtime-advanced-plugins.md
Quantum resistance runtime-advanced-quantum-resistance.md
Signature verification runtime-advanced-signature-verification.md

Runtime: Examples

Topic Reference File
Basic token runtime-examples-basic-token.md
NFT with reservations runtime-examples-nft-with-reservations.md
Stablecoin runtime-examples-stablecoin.md
Oracle integration runtime-examples-oracle-integration.md

Client: Getting Started (opnet package)

Topic Reference File
Client docs index client-README.md
Getting started overview client-getting-started-overview.md
Installation client-getting-started-installation.md
Quick start guide client-getting-started-quick-start.md

Client: Providers

Topic Reference File
Understanding providers client-providers-understanding-providers.md
JSON-RPC provider client-providers-json-rpc-provider.md
WebSocket provider client-providers-websocket-provider.md
Threaded HTTP client-providers-threaded-http.md
Internal caching client-providers-internal-caching.md
Advanced configuration client-providers-advanced-configuration.md

Client: Contract Interactions

Topic Reference File
Contracts overview client-contracts-overview.md
Instantiating contracts client-contracts-instantiating-contracts.md
Simulating calls client-contracts-simulating-calls.md
Sending transactions client-contracts-sending-transactions.md
Transaction configuration client-contracts-transaction-configuration.md
Gas estimation client-contracts-gas-estimation.md
Offline signing client-contracts-offline-signing.md
Contract code client-contracts-contract-code.md

Client: ABI Reference

Topic Reference File
ABI overview client-abi-reference-abi-overview.md
Data types client-abi-reference-data-types.md
Custom ABIs client-abi-reference-custom-abis.md
OP20 ABI client-abi-reference-op20-abi.md
OP20S ABI (signatures) client-abi-reference-op20s-abi.md
OP721 ABI client-abi-reference-op721-abi.md
Stablecoin ABIs client-abi-reference-stablecoin-abis.md
Factory ABIs client-abi-reference-factory-abis.md
MotoSwap ABIs client-abi-reference-motoswap-abis.md

Client: Bitcoin Operations

Topic Reference File
Balances client-bitcoin-balances.md
UTXOs client-bitcoin-utxos.md
Sending bitcoin client-bitcoin-sending-bitcoin.md
UTXO optimization client-bitcoin-utxo-optimization.md

Client: Blocks

Topic Reference File
Block operations client-blocks-block-operations.md
Gas parameters client-blocks-gas-parameters.md
Block witnesses client-blocks-block-witnesses.md
Reorg detection client-blocks-reorg-detection.md

Client: Epochs

Topic Reference File
Epochs overview client-epochs-overview.md
Epoch operations client-epochs-epoch-operations.md
Mining template client-epochs-mining-template.md
Submitting epochs client-epochs-submitting-epochs.md

Client: Storage, Transactions, Public Keys, Utils

Topic Reference File
Storage operations client-storage-storage-operations.md
Fetching transactions client-transactions-fetching-transactions.md
Transaction receipts client-transactions-transaction-receipts.md
Broadcasting client-transactions-broadcasting.md
Challenges client-transactions-challenges.md
Public key operations client-public-keys-public-key-operations.md
Binary serialization client-utils-binary-serialization.md
Bitcoin utils client-utils-bitcoin-utils.md
Revert decoder client-utils-revert-decoder.md

Client: Examples

Topic Reference File
OP20 examples (transfers, balances) client-examples-op20-examples.md
OP721 examples (NFTs) client-examples-op721-examples.md
Advanced swaps (MotoSwap) client-examples-advanced-swaps.md
Deployment examples client-examples-deployment-examples.md

Client: API Reference

Topic Reference File
Provider API client-api-reference-provider-api.md
Contract API client-api-reference-contract-api.md
Epoch API client-api-reference-epoch-api.md
Types and interfaces client-api-reference-types-interfaces.md
UTXO Manager API client-api-reference-utxo-manager-api.md

Transaction Building (@btc-vision/transaction)

Topic Reference File
Transaction docs index transaction-README.md
Transaction building (TransactionFactory, UTXO flow, fees, signing) transaction-transaction-building.md
Offline transaction signing transaction-offline-transaction-signing.md
P2OP addresses transaction-addresses-P2OP.md
P2WDA addresses transaction-addresses-P2WDA.md

Transaction: Quantum Support (ML-DSA)

Topic Reference File
Quantum support overview transaction-quantum-support-README.md
Introduction to quantum resistance transaction-quantum-support-01-introduction.md
Mnemonic and wallet transaction-quantum-support-02-mnemonic-and-wallet.md
Address generation transaction-quantum-support-03-address-generation.md
Message signing transaction-quantum-support-04-message-signing.md
Address verification transaction-quantum-support-05-address-verification.md

Package READMEs

Package Reference File
opnet (client SDK) opnet-README.md
@btc-vision/btc-runtime (smart contract runtime) btc-vision-btc-runtime-README.md
@btc-vision/transaction btc-vision-transaction-README.md
@btc-vision/bitcoin (fork of bitcoinjs-lib) btc-vision-bitcoin-README.md
@btc-vision/ecpair btc-vision-ecpair-README.md
@btc-vision/bip32 btc-vision-bip32-README.md
@btc-vision/post-quantum (ML-DSA) btc-vision-post-quantum-README.md
@btc-vision/bsi-common btc-vision-bsi-common-README.md
@btc-vision/bitcoin-rpc btc-vision-bitcoin-rpc-README.md
@btc-vision/logger btc-vision-logger-README.md

Additional Package Documentation

Document Reference File
@btc-vision/bitcoin coding standards btc-vision-bitcoin-HOW_TO_WRITE_GOOD_CODE.md
@btc-vision/btc-runtime SECURITY btc-vision-btc-runtime-SECURITY.md
@btc-vision/bitcoin SECURITY btc-vision-bitcoin-SECURITY.md
@btc-vision/bitcoin CHANGELOG btc-vision-bitcoin-CHANGELOG.md
@btc-vision/bitcoin CONTRIBUTING btc-vision-bitcoin-CONTRIBUTING.md
@btc-vision/bitcoin AUDIT btc-vision-bitcoin-AUDIT.md
@btc-vision/transaction SECURITY btc-vision-transaction-SECURITY.md
@btc-vision/transaction CHANGELOG btc-vision-transaction-CHANGELOG.md
@btc-vision/transaction CONTRIBUTING btc-vision-transaction-CONTRIBUTING.md
@btc-vision/transaction AUDIT btc-vision-transaction-AUDIT.md
opnet SECURITY opnet-SECURITY.md
opnet CHANGELOG opnet-CHANGELOG.md
opnet CONTRIBUTING opnet-CONTRIBUTING.md
opnet bug report template opnet-github-bug-report.md
opnet feature request template opnet-github-feature-request.md
opnet PR template opnet-github-pull-request-template.md
@btc-vision/bitcoin test fixtures btc-vision-bitcoin-test-fixtures.md
@btc-vision/bsi-common LICENSE btc-vision-bsi-common-LICENSE.md
@btc-vision/bitcoin-rpc LICENSE btc-vision-bitcoin-rpc-LICENSE.md
@btc-vision/logger CONTRIBUTING btc-vision-logger-CONTRIBUTING.md
@btc-vision/logger LICENSE btc-vision-logger-LICENSE.md

TypeScript Configurations

Package Reference File
@btc-vision/bitcoin tsconfig btc-vision-bitcoin-tsconfig.md
@btc-vision/transaction tsconfig btc-vision-transaction-tsconfig.md
@btc-vision/bitcoin-rpc tsconfig btc-vision-bitcoin-rpc-tsconfig.md
@btc-vision/bsi-common tsconfig btc-vision-bsi-common-tsconfig.md
@btc-vision/logger tsconfig btc-vision-logger-tsconfig.md
opnet tsconfig opnet-tsconfig.md

Key Patterns

Client: Read a token balance

import { getContract, IOP20Contract, JSONRpcProvider, OP_20_ABI } from 'opnet';
import { Address } from '@btc-vision/transaction';
import { networks } from '@btc-vision/bitcoin';

const provider = new JSONRpcProvider('https://regtest.opnet.org', networks.regtest);
const token = getContract<IOP20Contract>(Address.fromString('0x...'), OP_20_ABI, provider, networks.regtest);
const result = await token.balanceOf(Address.fromString('0x...'));
console.log(result.properties.balance); // bigint

Client: Send a token transfer

import { TransactionParameters } from 'opnet';
import { Mnemonic, MLDSASecurityLevel, AddressTypes } from '@btc-vision/transaction';

const mnemonic = new Mnemonic('seed phrase...', '', network, MLDSASecurityLevel.LEVEL2);
const wallet = mnemonic.deriveUnisat(AddressTypes.P2TR, 0);

const simulation = await token.transfer(recipient, amount, new Uint8Array(0));
if (simulation.revert) throw new Error(simulation.revert);

const tx = await simulation.sendTransaction({
    signer: wallet.keypair,
    mldsaSigner: wallet.mldsaKeypair,
    refundTo: wallet.p2tr,
    maximumAllowedSatToSpend: 10000n,
    feeRate: 10,
    network,
});

Smart Contract: Minimal OP20 token

import { u256 } from '@btc-vision/as-bignum/assembly';
import { Blockchain, BytesWriter, Calldata, OP20, OP20InitParameters } from '@btc-vision/btc-runtime/runtime';

@final
export class MyToken extends OP20 {
    public constructor() { super(); }

    public override onDeployment(_calldata: Calldata): void {
        const maxSupply = u256.fromString('100000000000000000000000000');
        this.instantiate(new OP20InitParameters(maxSupply, 18, 'MyToken', 'MTK'));
        this._mint(Blockchain.tx.origin, maxSupply);
    }
}

Critical Warnings

  1. Constructor runs every call: In OPNet, the constructor runs on every contract interaction, not just deployment. Never put initialization logic in the constructor; use onDeployment() instead.
  2. Always simulate before sending: Call the contract method first to get a CallResult, check .revert, then call .sendTransaction().
  3. Non-custodial contracts: Contracts cannot hold or transfer BTC. They verify transaction outputs against state.
  4. Partial reverts: Consensus-layer execution can revert while Bitcoin transfers in the same transaction remain valid.
  5. Use Mnemonic, not WIF: Always use Mnemonic class with deriveUnisat() for OPWallet compatibility and ML-DSA quantum support.
  6. BigInt everywhere: All token amounts, gas values, and satoshi amounts are bigint.
  7. Pointer uniqueness: Each storage variable in a contract must have a unique pointer. Pointer collisions corrupt state silently.
  8. Do not read the UTXO Manager example: It is not a recommended reference.
  9. MANDATORY: Read example-contracts.md before writing or auditing any OPNet contract. It contains production-grade source code for all standard contract types with correct patterns for storage pointers, payment verification, event emission, access control, and two-step ownership transfers.
  10. MANDATORY: Read typescript-law.md before writing ANY TypeScript code. It defines strict coding standards including forbidden types, defensive programming requirements, error handling patterns, and security rules that all code must follow.
  11. MANDATORY: Read btc-runtime docs before writing any smart contract. The runtime-* reference files contain the complete API for Blockchain, storage, events, types, cross-contract calls, plugins, reentrancy guards, and all contract base classes. These are essential for correct contract development.
  12. OPNet does NOT use OP_RETURN. OPNet uses P2WDA (witness data authentication) to embed data in SegWit witness fields at ~75% lower cost than OP_RETURN. References to OP_RETURN in the bitcoin-scripts and transaction-configuration docs describe raw Bitcoin script capabilities that contracts can construct, not OPNet's own data embedding. Never state or imply that OPNet uses OP_RETURN.
Weekly Installs
4
Repository
btc-vision/opnet-skills
First Seen
Feb 2, 2026
Installed on
claude-code4
cursor2
codex2
mcpjam1
command-code1
crush1