UpdateCustodianMultisigWallet.abi.json

Overview

This file defines the Application Binary Interface (ABI) for a multisignature wallet smart contract focused on managing custodians and multisig transactions. The wallet supports multiple owners (custodians), transaction submissions requiring multiple confirmations, and data update proposals with confirmation mechanisms. It is designed to securely manage transactions and updates through a threshold of confirmations from the custodians.

The contract ABI version is 2.4 and includes definitions of functions, events, and state fields. The wallet supports features such as sending transactions, confirming transactions, updating custodian data, querying stored transactions and custodians, and adjusting operational parameters.

Functionality Details

Constructor

constructor(
  owners_pubkey: uint256[],
  owners_address: address[],
  reqConfirms: uint8,
  reqConfirmsData: uint8,
  value: uint64
)

• Initializes the multisig wallet with a set of custodians.

• Parameters:

  • owners_pubkey: List of public keys for the owners.

  • owners_address: List of corresponding owner addresses.

  • reqConfirms: Number of confirmations required to approve a transaction.

  • reqConfirmsData: Number of confirmations required to approve a data update.

  • value: Initial value for the wallet.

• Outputs: None.

setMaxCleanupOperations

setMaxCleanupOperations(value: uint256)

• Sets the maximum number of cleanup operations allowed.

• Parameters:

  • value: The maximum number of cleanup operations.

• Outputs: None.

sendTransaction

sendTransaction(
  dest: address,
  value: uint128,
  cc: map(uint32, varuint32),
  bounce: bool,
  flags: uint8,
  payload: cell
) -> address

• Sends a transaction from the wallet to a specified destination.

• Parameters:

  • dest: Destination address of the transaction.

  • value: Amount of currency to send.

  • cc: A map of callback codes or custom codes.

  • bounce: Boolean flag indicating if the transaction should bounce on failure.

  • flags: Transaction flags affecting sending behavior.

  • payload: Additional data or payload encoded as a cell.

• Returns:

  • Address representing the sent transaction or related resource.

submitTransaction

submitTransaction(
  dest: address,
  value: uint128,
  cc: map(uint32, varuint32),
  bounce: bool,
  flag: uint8,
  payload: cell
) -> uint64

• Submits a new transaction for approval by custodians.

• Parameters: Same as sendTransaction.

• Returns:

  • transId: Unique identifier (uint64) for the submitted transaction.

confirmTransaction

confirmTransaction(transactionId: uint64)

• Confirms a submitted transaction by a custodian.

• Parameters:

  • transactionId: The ID of the transaction to confirm.

• Outputs: None.

submitDataUpdate

submitDataUpdate(
  owners_pubkey: uint256[],
  owners_address: address[],
  reqConfirms: uint8,
  reqConfirmsData: uint8
) -> uint64

• Submits a proposal to update custodian data and confirmation requirements.

• Parameters:

  • owners_pubkey: Updated list of owners' public keys.

  • owners_address: Updated list of owners' addresses.

  • reqConfirms: New required confirmations for transactions.

  • reqConfirmsData: New required confirmations for data updates.

• Returns:

  • transId: Identifier for the data update proposal.

confirmDataUpdate

confirmDataUpdate(dataUpdateId: uint64)

• Confirms a submitted data update proposal.

• Parameters:

  • dataUpdateId: The ID of the data update to confirm.

• Outputs: None.

isConfirmed

isConfirmed(mask: uint32, index: uint8) -> bool

• Checks if a given confirmation mask includes confirmation from a specific custodian index.

• Parameters:

  • mask: Bitmask representing confirmations.

  • index: Custodian index.

• Returns:

  • confirmed: Boolean indicating if the custodian has confirmed.

getParameters

getParameters() -> {
  maxQueuedTransactions: uint8,
  maxCustodianCount: uint8,
  expirationTime: uint64,
  requiredTxnConfirms: uint8,
  requiredDataConfirms: uint8
}

• Retrieves configuration parameters of the wallet.

• Returns:

  • maxQueuedTransactions: Maximum number of transactions queued.

  • maxCustodianCount: Maximum number of custodians supported.

  • expirationTime: Expiration time for transactions/updates.

  • requiredTxnConfirms: Number of required confirmations for transactions.

  • requiredDataConfirms: Number of required confirmations for data updates.

getTransaction

getTransaction(transactionId: uint64) -> trans: tuple

• Retrieves detailed information about a specific transaction.

• Parameters:

  • transactionId: ID of the transaction.

• Returns:

  • trans: A tuple containing:

    • id: Transaction ID.

    • confirmationsMask: Bitmask of confirmations.

    • signsRequired: Number of required signatures.

    • signsReceived: Number of signatures received.

    • creator: Custodian tuple who created the transaction.

    • dest: Destination address.

    • value: Transfer value.

    • cc: Custom codes map.

    • sendFlags: Flags controlling the send behavior.

    • payload: Payload data.

    • bounce: Bounce flag.

getUpdateData

getUpdateData(updateDataId: uint64) -> data: tuple

• Retrieves a data update proposal by ID.

• Parameters:

  • updateDataId: ID of the data update.

• Returns:

  • data: Tuple containing update details including IDs, confirmations, new owners, and confirmation requirements.

getTransactions

getTransactions() -> transactions: tuple[]

• Returns a list of all stored transactions with details similar to getTransaction.

getUpdateDatas

getUpdateDatas() -> data: tuple[]

• Returns a list of all stored data update proposals.

getTransactionIds

getTransactionIds() -> ids: uint64[]

• Retrieves a list of all transaction IDs currently stored.

getUpdateCodeIds

getUpdateCodeIds() -> ids: uint64[]

• Retrieves a list of all data update proposal IDs.

getCustodians

getCustodians() -> custodians: tuple[]

• Returns a list of all custodians currently registered.

• Each custodian tuple contains optional public key, optional address, and index.

getVersion

getVersion() -> (string, string)

• Returns the version information of the contract.

• Returns:

  • Two strings: could represent major and minor version info or related metadata.

Events

TransferAccepted

event TransferAccepted(payload: bytes)

• An event triggered when a transfer transaction is accepted.

• Parameters:

  • payload: Raw bytes payload associated with the transfer.

State Fields

• _pubkey (uint256, init): Public key of the contract owner or deployer.

• _timestamp (uint64): Timestamp of the last relevant action.

• _constructorFlag (bool): Flag indicating constructor execution state.

• m_ownerKey (optional(uint256)): Current custodian public key.

• m_ownerAddress (optional(address)): Current custodian address.

• m_requestsMask (uint256): Bitmask tracking transaction confirmations.

• m_requestsMaskData (uint256): Bitmask tracking data update confirmations.

• m_transactions (map(uint64, tuple)): Mapping of transaction IDs to transaction details.

• m_data (map(uint64, tuple)): Mapping of data update IDs to update proposals.

• m_custodians (map(uint256, tuple)): Mapping of custodian indexes to custodian details.

• m_custodianCount (uint8): Number of custodians.

• m_defaultRequiredConfirmations (uint8): Default transaction confirmation threshold.

• m_defaultRequiredConfirmationsData (uint8): Default data update confirmation threshold.

• _max_cleanup_operations (uint256): Maximum allowed cleanup operations.

Implementation Details and Algorithms

• The multisig wallet enforces security by requiring multiple custodian confirmations for transactions and data updates.

• Confirmations are tracked using bitmasks (m_requestsMask for transactions and m_requestsMaskData for data updates), allowing efficient storage and verification of which custodians have approved.

• Custodians are stored both by public key and address, with optional presence, and are indexed for efficient lookup and confirmation checks.

• Transactions and data updates are stored in maps, keyed by unique 64-bit IDs, enabling retrieval and management of multiple pending or historical proposals.

• The wallet supports updates to the custodian set and confirmation thresholds through a data update proposal and confirmation mechanism, enhancing flexibility and governance.

• The sendTransaction and submitTransaction functions differentiate between immediate transaction sending and staged transaction submission requiring confirmation.

• Payloads associated with transactions are stored as cells, enabling complex data structures to be passed and processed.

• The isConfirmed function facilitates checking if a particular custodian has confirmed a transaction or update by inspecting bits in the confirmation mask.

Interaction with Other System Components

• This ABI acts as the interface for interacting with the multisig wallet smart contract deployed on a blockchain.

• External components such as user interfaces, backend services, or other smart contracts will invoke these functions to:

  • Submit, confirm, and send transactions.

  • Manage custodian sets and confirmation rules.

  • Query transaction and update states.

• Events like TransferAccepted provide asynchronous notifications about transaction acceptance to listeners or off-chain services.

• The wallet's custodians and transaction confirmations ensure multi-party authorization before funds or state changes occur, integrating into broader wallet management or decentralized governance frameworks.

Visual Diagram

classDiagram
class MultisigWallet {
+constructor()
+setMaxCleanupOperations()
+sendTransaction()
+submitTransaction()
+confirmTransaction()
+submitDataUpdate()
+confirmDataUpdate()
+isConfirmed()
+getParameters()
+getTransaction()
+getUpdateData()
+getTransactions()
+getUpdateDatas()
+getTransactionIds()
+getUpdateCodeIds()
+getCustodians()
+getVersion()
-_pubkey
-_timestamp
-_constructorFlag
-m_ownerKey
-m_ownerAddress
-m_requestsMask
-m_requestsMaskData
-m_transactions
-m_data
-m_custodians
-m_custodianCount
-m_defaultRequiredConfirmations
-m_defaultRequiredConfirmationsData
-_max_cleanup_operations
}