owner_wallet.rs

Overview

This file provides functionality for interacting with owner wallet accounts within the system, specifically focusing on decoding the signing public key stored in such wallets. It supports two types of token issuers—Block Keeper nodes and Block Manager nodes—each associated with a distinct ABI (Application Binary Interface). The main utility offered is a function to extract and decode the signing public key from the storage data of an account representing an owner wallet.

The file leverages components from several modules, including tvm_abi for token value representations, tvm_block for account abstractions, tvm_client for ABI handling and encoding utilities, and tvm_types for 256-bit unsigned integer operations. It also references a TokenIssuer type from the authentication module to determine the wallet type.

Constants and Static Data

• OWNER_WALLET_SIGN_KEY: A string constant "_signing_pubkey" used as the key name when decoding storage fields to identify the signing public key field.

• BK_OWNER_WALLET_ABI: The ABI JSON string for the Block Keeper Node Wallet, included from an external JSON file.

• BM_OWNER_WALLET_ABI: The ABI JSON string for the Block Manager Node Wallet, included from an external JSON file.

These ABIs define the data layout of the respective owner wallets and are essential for correctly decoding the storage content.

Functions

decode_signing_pubkey

pub fn decode_signing_pubkey(
    account: &Account,
    issuer: &TokenIssuer,
) -> anyhow::Result<Option<String>>

Purpose

Extracts and decodes the signing public key from the on-chain storage of a given owner wallet account. It returns the public key as a hexadecimal string if found.

Parameters

• account: &Account
  A reference to the account object representing the owner wallet. The account contains on-chain data in a cell format.

• issuer: &TokenIssuer
  A reference to the token issuer enum, which indicates whether the wallet belongs to a Block Keeper (Bk) or Block Manager (Bm) node. This determines which ABI to use for decoding.

Returns

• anyhow::Result<Option<String>>

  • Ok(Some(pubkey)) where pubkey is the signing public key as a hex string, if decoding succeeds and the key is present.

  • Ok(None) if the account has no data or the signing public key field is missing.

  • Err if any decoding or ABI parsing error occurs, with an error message describing the failure.

Description

1. The function attempts to retrieve the data cell from the account. If the account has no data, it returns Ok(None) early.

2. It converts the cell data into a slice using slice_from_cell, handling any errors during this conversion.

3. Depending on the variant of the issuer parameter (Bk or Bm), it selects the corresponding ABI JSON string.

4. The ABI JSON is parsed into an ABI object using the tvm_client::abi module.

5. The function decodes the storage fields of the cell slice according to the ABI, enabling access to named tokens stored in the wallet.

6. It iterates through the decoded tokens to find the one with the name corresponding to OWNER_WALLET_SIGN_KEY.

7. Upon locating this field, it verifies the token value is a 256-bit unsigned integer (Uint), converts it into a UInt256 type, and then formats it as a hexadecimal string.

8. The hex string of the signing public key is returned wrapped in Option.

Usage Example

use tvm_block::Account;
use crate::owner_wallet::decode_signing_pubkey;
use crate::auth::TokenIssuer;

// Suppose `account` is a loaded Account instance representing an owner wallet
// Suppose `issuer` is TokenIssuer::Bk or TokenIssuer::Bm

match decode_signing_pubkey(&account, &issuer) {
    Ok(Some(pubkey_hex)) => println!("Signing public key: {}", pubkey_hex),
    Ok(None) => println!("No signing public key found in account data."),
    Err(e) => eprintln!("Error decoding signing public key: {}", e),
}

Implementation Details

• Cell to Slice Conversion: The data stored in the account is a serialized cell structure. To decode it, the function converts the cell into a slice representation which is suitable for ABI decoding.

• ABI-based Decoding: The function relies on ABI specifications (BK_OWNER_WALLET_ABI or BM_OWNER_WALLET_ABI) to interpret the structure of the wallet's storage data. This approach ensures robust and versioned decoding.

• Token Value Inspection: Decoded storage fields are returned as tokens with names and typed values. The function searches for the token named "_signing_pubkey" and expects it to be a 256-bit unsigned integer. The underlying number is converted to a byte array and then to a hex string.

• Error Handling: Uses the anyhow crate to produce descriptive errors in case of failures, such as missing data, decoding errors, or ABI parsing issues.

Interactions with Other Components

• Account (tvm_block::Account): The wallet account data is provided by this type. The file depends on the account's ability to provide its data cell.

• TokenIssuer (crate::auth::TokenIssuer): Determines the ABI to use for decoding, reflecting different wallet implementations for Block Keeper and Block Manager nodes.

• ABI Handling (tvm_client::abi): The file uses this for parsing ABI JSON and decoding storage fields accordingly.

• TokenValue (tvm_abi::TokenValue) and UInt256 (tvm_types::UInt256): Used to handle and convert the decoded token data into a usable public key format.

• ABI JSON Files: The file includes external ABI JSON files which define the data schema for the two wallet types.

This file acts as a bridge between the raw on-chain wallet data (in the form of serialized cells) and higher-level application logic requiring access to the public signing key.

Mermaid Class Diagram

classDiagram
class OwnerWallet {
<<static>>
+decode_signing_pubkey(account: &Account, issuer: &TokenIssuer) Result<Option<String>>
}
class Account {
+get_data() Option<Cell>
}
class TokenIssuer {
<<enum>>
Bk
Bm
}
class Abi {
+decode_storage_fields(slice, bool) Result<Vec<Token>>
+abi() Result<Abi>
}
class Token {
+name: String
+value: TokenValue
}
class TokenValue {
<<enum>>
Uint
// other variants
}
class UInt256 {
+from_be_bytes(bytes: &[u8]) UInt256
+to_hex_string() String
}
OwnerWallet ..> Account : uses
OwnerWallet ..> TokenIssuer : uses
OwnerWallet ..> Abi : uses
Abi "1" -- "*" Token : returns
Token "1" -- "1" TokenValue : contains
TokenValue ..> UInt256 : converts

This diagram represents the primary entities and their relationships involved in decoding the signing public key within this file. The OwnerWallet static context provides the decoding function which utilizes Account, TokenIssuer, and ABI parsing features to extract the Token of interest and convert it into a UInt256 representation.