Token Ownership

Require specific token holdings from the initiator as a prerequisite for transfer approval. This approval criteria checks on-chain balances to ensure users own required tokens before allowing transfers.

Overview

Token ownership requirements enable gating mechanisms where users must possess specific tokens to access certain transfers. This creates dependency relationships between collections and enables sophisticated access control systems.

Key Benefits:

• Access Control: Gate transfers based on token ownership

• Collection Dependencies: Create relationships between different collections

• On-Chain Verification: Automatic balance checking without external data

• Flexible Requirements: Support for amount ranges, time-based ownership, and multiple token types

Interface

interface MustOwnTokens<T extends NumberType> {
    collectionId: T;
    amountRange: UintRange<T>; // Min/max amount expected
    ownershipTimes: UintRange<T>[];
    tokenIds: UintRange<T>[];

    overrideWithCurrentTime: boolean; // Use current block time. Overrides ownershipTimes with [{ start: currentTime, end: currentTime }]
    mustSatisfyForAllAssets: boolean; // All vs one requirement
    ownershipCheckParty: string; // Which party to check ownership for: "initiator", "sender", "recipient", or a hardcoded bb1 address (default: "initiator" if empty)
}

Field Descriptions

collectionId

• Type: T (NumberType)

• Description: The ID of the collection containing the required tokens

• Example: "1" for collection ID 1

amountRange

• Type: UintRange<T>

• Description: Minimum and maximum amount of tokens the user must own

• Format: { start: "minAmount", end: "maxAmount" }

• Example: { start: "1", end: "10" } requires 1-10 tokens (amounts)

ownershipTimes

• Type: UintRange<T>[]

• Description: Time ranges when the user must have owned the tokens (UNIX milliseconds)

• Example: [{ start: "1691931600000", end: "1723554000000" }] for Aug 13, 2023 - Aug 13, 2024

tokenIds

• Type: UintRange<T>[]

• Description: Specific token IDs that must be owned

• Example: [{ start: "1", end: "100" }] for token IDs 1-100

overrideWithCurrentTime

• Type: boolean

• Description: When true, ignores ownershipTimes and uses current block time

• Behavior: Sets ownership time to [{ start: currentTime, end: currentTime }]

• Use Case: Require current ownership only, not historical ownership

mustSatisfyForAllAssets

• Type: boolean

• Description: Controls whether all specified token requirements must be met or just one

• True: User must own ALL specified token combinations

• False: User must own AT LEAST ONE of the specified token combinations

ownershipCheckParty

• Type: string

• Description: Specifies which party of the transfer to check ownership for

• Options:

  • "initiator" (default): Check ownership for the address that initiated the transfer

  • "sender": Check ownership for the address sending the tokens

  • "recipient": Check ownership for the address receiving the tokens

  • Hardcoded bb1 address (e.g., "bb1kj9kt5y64n5a8677fhjqnmcc24ht2vy9atmdls"): Check ownership for a specific address, regardless of transfer parties

• Default: "initiator" (if empty or not specified)

• Example: "sender" to require the sender to own specific tokens before allowing the transfer

• Hardcoded Address Example: "bb1kj9kt5y64n5a8677fhjqnmcc24ht2vy9atmdls" to require a specific address to own tokens (useful for multi-sig or contract-based checks)

Example

Require users to own specific tokens to access premium features or exclusive transfers.

{
    "mustOwnTokens": [
        {
            "collectionId": "1",
            "amountRange": { "start": "1", "end": "1" },
            "ownershipTimes": [{ "start": "1", "end": "18446744073709551615" }],
            "tokenIds": [{ "start": "1", "end": "1" }],
            "overrideWithCurrentTime": false,
            "mustSatisfyForAllAssets": true,
            "ownershipCheckParty": "initiator"
        }
    ]
}

Party-Specific Examples

Check Initiator Ownership (Default)

{
    "mustOwnTokens": [
        {
            "collectionId": "1",
            "amountRange": { "start": "1", "end": "1" },
            "tokenIds": [{ "start": "1", "end": "1" }],
            "ownershipCheckParty": "initiator"
        }
    ]
}

Check Sender Ownership

{
    "mustOwnTokens": [
        {
            "collectionId": "1",
            "amountRange": { "start": "1", "end": "1" },
            "tokenIds": [{ "start": "1", "end": "1" }],
            "ownershipCheckParty": "sender"
        }
    ]
}

Check Recipient Ownership

{
    "mustOwnTokens": [
        {
            "collectionId": "1",
            "amountRange": { "start": "1", "end": "1" },
            "tokenIds": [{ "start": "1", "end": "1" }],
            "ownershipCheckParty": "recipient"
        }
    ]
}

Check Hardcoded Address Ownership

You can also specify a hardcoded bb1 address to check ownership for a specific address, regardless of who is involved in the transfer. This is useful for multi-sig wallets, contract addresses, or other scenarios where you need to verify ownership for a specific address.

{
    "mustOwnTokens": [
        {
            "collectionId": "1",
            "amountRange": { "start": "1", "end": "1" },
            "tokenIds": [{ "start": "1", "end": "1" }],
            "ownershipCheckParty": "bb1kj9kt5y64n5a8677fhjqnmcc24ht2vy9atmdls"
        }
    ]
}

This example requires the address bb1kj9kt5y64n5a8677fhjqnmcc24ht2vy9atmdls to own the specified tokens, regardless of who initiates, sends, or receives the transfer.