General Best Practices

Recommendations

The following best practices apply broadly across all areas of the opnet client library. Adopting these patterns consistently ensures that your applications remain reliable, performant, and maintainable as they scale.

Error Handling

All operations in the library can fail due to network issues, invalid parameters, or contract reverts. Wrap calls in try-catch-finally blocks to handle failures and ensure proper resource cleanup. See the Error Handling section for details.

Handle BigInt Correctly

All token amounts, balances, fees, and satoshi values throughout the library are represented as bigint types. This guarantees arbitrary-precision integer arithmetic and eliminates the floating-point rounding errors that JavaScript's number type introduces at large values. Always use the n suffix for literal values (e.g., 100_00000000n) and avoid mixing bigint with number in arithmetic operations.

// Token amounts are always bigint
const amount = 100_00000000n;  // 100 tokens with 8 decimals

// Never use Number for large values
const wrong = Number(balance);  // May lose precision!

// Token amounts are always bigint
const amount = 100_00000000n;  // 100 tokens with 8 decimals

// Never use Number for large values
const wrong = Number(balance);  // May lose precision!

Use Type-safe Interfaces

Leverage TypeScript's type system when interacting with contracts by using the provided ABI interfaces such as IOP20Contract and IOP721Contract, or by defining your own typed interfaces for custom contracts. These interfaces enforce correct method signatures, parameter types, and return types at compile time, catching errors before they reach the network.

// Type-safe contract interface
interface IMyToken extends IOP20Contract {
    mint(to: Address, amount: bigint): Promise<CallResult<never>>;
}

// Generic contract instantiation
const token = getContract<IMyToken>(
    address,
    myTokenABI,
    provider,
    network
);

// Type-checked method calls
const result = await token.mint(recipient, 1000n);
//                    ^^^^^ TypeScript knows this returns CallResult<never>

// Type-safe contract interface
interface IMyToken extends IOP20Contract {
    mint(to: Address, amount: bigint): Promise<CallResult<never>>;
}

// Generic contract instantiation
const token = getContract<IMyToken>(
    address,
    myTokenABI,
    provider,
    network
);

// Type-checked method calls
const result = await token.mint(recipient, 1000n);
//                    ^^^^^ TypeScript knows this returns CallResult<never>