GiverV3.abi.json

Overview

This file defines the Application Binary Interface (ABI) for the GiverV3 smart contract, specifying its version, header, functions, events, and fields. The ABI acts as a contract between the contract and clients (or other contracts), detailing how to encode function calls and decode responses. This ABI adheres to version 2 with header parameters for time and expire, indicating that transactions include timing constraints for validity.

The GiverV3 contract is primarily designed to send tokens or currency to specified addresses with flexible options, record messages, and support contract upgrades. It also emits events to signal the execution of currency transfers. The ABI provides the necessary interface for interacting with the contract's functions programmatically.

ABI Structure and Components

Header

time: Timestamp included in the message header.
expire: Expiration time for messages, establishing a validity period.

Fields

Field Name	Type	Initialization	Description
_pubkey	`uint256`	`true`	Public key initialized during contract setup.
_timestamp	`uint64`	`false`	Stores timestamp, likely updated during operations.
`_constructorFlag`	`bool`	`false`	Flag to indicate constructor state or initialization.
`m_messages`	`map(uint256,uint32)`	`false`	Mapping which stores messages; keys are `uint256` hashes, values are expiration timestamps (`uint32`).

Functions

constructor

Purpose: Initializes the contract upon deployment.
Inputs: None
Outputs: None
Usage: Called once during the contract deployment phase to set initial state variables such as _pubkey.

sendTransaction

Purpose: Sends a transaction to a specified destination address with an optional bounce flag.
Inputs:
- dest (address): The address to send the transaction to.
- value (varuint16): The amount of currency to send.
- bounce (bool): If true, the transaction will bounce back on failure.
Outputs: None

Usage Example:

contract.sendTransaction(destAddress, 1000, true);

Details: This function allows sending currency with an optional bounce mechanism, which can be used for error handling or reverting failed transactions.

sendCurrency

Purpose: Sends currency along with an Extended Currency Collection (ECC) to a destination address.
Inputs:
- dest (address): Destination address.
- value (varuint16): Currency amount.
- ecc (map(uint32,varuint32)): Mapping representing ECC data.
Outputs: None

Usage Example:

const eccMap = new Map([[1, 100], [2, 50]]);
contract.sendCurrency(destAddress, 500, eccMap);

Details: The ECC map allows attaching additional currency data or tokens, enabling more complex currency interactions beyond simple transfers.

sendCurrencyWithFlag

Purpose: Sends currency with ECC data and an additional flag parameter to the destination address.
Inputs:
- dest (address): Destination address.
- value (varuint16): Currency amount.
- ecc (map(uint32,varuint32)): ECC data.
- flag (uint8): A flag for additional transfer options or behaviors.
Outputs: None

Usage Example:

const eccMap = new Map([[1, 100]]);
contract.sendCurrencyWithFlag(destAddress, 1000, eccMap, 1);

Details: The flag parameter is used to modify or specify transfer behavior, such as priority or special handling.

sendFreeToken

Purpose: Sends a free token to a specified destination address.
Inputs:
- dest (address): Destination address.
Outputs: None
Usage Example:
```
contract.sendFreeToken(destAddress);
```
Details: This function allows sending tokens without specifying a value, likely for promotional or incentivization purposes.

getMessages

Purpose: Retrieves stored messages from the contract.
Inputs: None
Outputs:
- messages (tuple[]): An array of tuples containing:
  - hash (uint256): Hash of the message.
  - expireAt (uint32): Expiration timestamp of the message.

Usage Example:

const messages = contract.getMessages();
messages.forEach(msg => {
  console.log(`Message hash: ${msg.hash}, expires at: ${msg.expireAt}`);
});

Details: This function reads the internal m_messages mapping and returns all stored messages with their expiration details.

upgrade

Purpose: Upgrades the contract code to new logic.
Inputs:
- newcode (cell): Encoded new contract code.
Outputs: None
Usage Example:
```
contract.upgrade(newCodeCell);
```
Details: Enables updating the contract's functionality post-deployment by replacing the existing code with newcode. This supports maintainability and feature enhancements.

Events

Events facilitate off-chain clients or other contracts to listen to important state changes or actions.

SentCurrency

Triggered When: Currency is sent using sendCurrency.
Inputs:
- dst (address): Destination address.
- value (varuint16): Amount sent.
- value2 (map(uint32,varuint32)): ECC data sent alongside.
Outputs: None

SentCurrencyWithFlag

Triggered When: Currency is sent using sendCurrencyWithFlag.
Inputs:
- dst (address): Destination address.
- value (varuint16): Amount sent.
- value2 (map(uint32,varuint32)): ECC data.
- flag (uint8): Flag used during sending.
Outputs: None

Implementation Details and Algorithms

Message Storage: Messages are stored in a map (m_messages) keyed by a 256-bit hash, with an associated expiration timestamp (uint32). This provides an efficient way to keep track of messages and their validity.
Currency Sending: The contract supports multiple methods for sending currency:
- Basic transactions (sendTransaction)
- Transactions with complex data attached via ECC maps (sendCurrency, sendCurrencyWithFlag)
- Free token sending (sendFreeToken)
Upgradeability: The upgrade function accepts a new serialized contract code (cell), enabling the contract to be replaced or extended while preserving state.

Interaction with Other System Components

This ABI file defines the interface for external clients and other contracts to interact with the GiverV3 contract.
Functions like sendTransaction and sendCurrency interact with other smart contracts or wallet addresses by transferring tokens or currency.
The upgrade function interacts with the blockchain's contract deployment mechanism to replace the contract code.
Events such as SentCurrency and SentCurrencyWithFlag serve as hooks for off-chain listeners or other contracts to react to currency transfers.

Visual Diagram: Flowchart of Main Functions and Their Relationships

flowchart TD
A[constructor] --> B[sendTransaction]
A --> C[sendCurrency]
A --> D[sendCurrencyWithFlag]
A --> E[sendFreeToken]
A --> F[getMessages]
A --> G[upgrade]
B --> H[External Address]
C --> H
D --> H
E --> H
C --> I[ECC Map]
D --> I
D --> J[Flag]
F --> K[m_messages storage]
G --> L[New Contract Code]

The diagram illustrates how the contract initializes via constructor, then supports several currency sending functions that interact with external addresses, optionally making use of ECC maps and flags. The getMessages function reads from internal storage, while upgrade replaces contract code with new logic.