Gift Vault V2

Overview

Gift Vault V2 allows you to assign an X (Twitter) account as the Gift Owner for a token launched through VaultPortal. The gift owner can prove control of that X account and direct the vault's fee flow to any EVM address of their choice.

The core mechanism is:

1. Assign Gift Owner: The X account you specify becomes the gift owner for the vault.

2. Accumulating Phase: After launch, the vault first stays in ACCUMULATING mode and holds incoming native BNB fees.

3. Flexible Beneficiary: Once the gift owner proves control, the vault enters STREAMING mode and routes fees to the chosen EVM address.

4. 7-Day Grace Period: If the gift owner does not take over within the grace period, the gift flow is closed.

5. Fallback: Holder Dividends: After timeout, the vault enters DIVIDEND mode and routes value to token holders.

Compared with the legacy Gift Vault (FlapXVault), Gift Vault V2 mainly brings:

• two V2 product options

• a new vault lifecycle: ACCUMULATING -> STREAMING -> DIVIDEND

• new launch constraints for the V2 product line

• holder-dividend fallback instead of buyback & burn

Important: VaultPortal here is not the same contract as the Flap Bonding Curve Protocol Portal.

Legacy Gift Vault vs Gift Vault V2

The old gift-vault.md document is for the legacy Gift Vault flow. This document is for the new Gift Vault V2 product line.

For integrators, the practical differences are:

Topic	Gift Vault V1	Gift Vault V2
Product options	one legacy Gift Vault flow	two product options: GiftV4VaultFactoryV2 and GiftTaxVaultFactoryV2
API integration	existing API	same API, request format, and response format as V1
Fee routing lifecycle	legacy gift flow	ACCUMULATING -> STREAMING -> DIVIDEND
Timeout fallback	buyback & burn	holder dividends
What you need to update	legacy integration	mainly factory selection and launch-parameter validation

So if you already support Gift Vault V1, the main work for V2 is not rewriting your API integration. The main work is choosing the correct V2 factory and respecting the V2 launch constraints.

Network Details

BNB Smart Chain Mainnet

• GiftV4VaultFactoryV2: 0x6909aD1822Ece349CDDAb98E6F62EeeD9fAa2e10

• GiftTaxVaultFactoryV2: 0xFb7ccc4Fd09Da5b7016A18d51e227Af4ABE53f44

BNB Smart Chain Testnet

• GiftV4VaultFactoryV2: 0xaa00b4CeFeE8b4BF7D2E23C21ae82cfC9AFC9D67

• GiftTaxVaultFactoryV2: 0x2eDD880AB36b07bD030BDa28A13c3E9148C11622

Product matrix

Gift Vault V2 has two product options. The difference is mainly the launch constraints of the selected factory.

GiftV4VaultFactoryV2

Use this factory for the zero-tax Gift V4 product.

Launch constraints:

• tokenVersion == TOKEN_V3_PERMIT

• quoteToken == address(0)

• buyTaxRate == 0

• sellTaxRate == 0

• dividendBps == 0

• dividendToken == address(0)

GiftTaxVaultFactoryV2

Use this factory for the taxed Gift product.

Launch constraints:

• tokenVersion == TOKEN_TAXED_V3

• quoteToken == address(0)

• buyTaxRate == sellTaxRate

• buyTaxRate / sellTaxRate must both be one of:

  • 100 (1%)

  • 200 (2%)

  • 300 (3%)

• dividendBps == 0

• dividendToken == address(0)

Shared launch-time vault data

For both Gift Vault V2 product options, the only launch-time vault parameter is the gift owner's X handle.

Lifecycle

Gift Vault V2 has three states:

1. ACCUMULATING

• initial state after deployment

• vault accepts native BNB fees from the token

• funds stay inside the vault

• waiting for a valid X proof to assign the streaming recipient

2. STREAMING

• entered after a valid manageByProof() call

• all accumulated BNB is flushed immediately to streamingTarget

• future BNB is forwarded to the same target on receipt

• the target can be updated again by a newer valid proof

3. DIVIDEND

• entered after createdAt + timeoutPeriod if streaming was never activated

• sticky once entered

• vault wraps native BNB into the dividend token (normally WBNB)

• vault deposits the wrapped balance into the token's Dividend contract for holders

Default timeout for newly created vaults is 7 days, configurable at the factory level for future vaults.

API compatibility with Gift Vault V1

gift vault v1 and gift vault v2 use the same API interface.

This means:

• the API endpoints are the same

• the request format is the same

• the response format is the same

• existing V1 API integration code can be reused for V2 directly

So if you have already integrated the API in Gift Vault (FlapXVault), you do not need to change your request / response parsing logic for V2.

What is different in V2

For API integrators, the main V2 differences are:

• the factory addresses are different

• there are now two V2 product options

• launch constraints are different depending on which product you choose

• the vault lifecycle is now ACCUMULATING -> STREAMING -> DIVIDEND

• the fallback behavior is holder dividends instead of buyback & burn

Integration notes

When integrating Gift Vault V2, the main things you need to do are:

1. choose the correct Gift V2 factory address

2. launch through VaultPortal

3. pass the gift owner's xHandle in vaultData

4. keep using the same API request / response handling as V1

5. update your product selection logic to match the V2 launch constraints

Launch data

For Gift Vault V2, the only launch-time vault parameter is the gift owner's X handle.

Product selection

• use GiftV4VaultFactoryV2 for the zero-tax Gift V4 product

• use GiftTaxVaultFactoryV2 for the taxed Gift product

For GiftTaxVaultFactoryV2, buy tax and sell tax should use the same preset, and the supported presets are 1%, 2%, or 3%.

Summary

If you already support Gift Vault V1 API integration, then Gift Vault V2 is mainly a product / factory upgrade, not an API upgrade.

In most cases, you only need to:

• switch to the correct V2 factory address

• choose the correct V2 product type

• respect the new launch constraints

• keep the existing API request / response integration unchanged