JSON parameters#

This guide explains how to interact with the CIS-2 smart contract functions by providing input JSON parameters. This guide uses the cis2-multi smart contract as a starting point, and then continues with a couple of custom input types.

transfer() and TransferParams#

Use the transfer() function to transfer some amount of token A from one account to another. The parameter to the transfer function is an array of Transfer s which is defined in CIS-2.

pub struct Transfer<T: IsTokenId, A: IsTokenAmount> {
    /// The ID of the token being transferred.
    pub token_id: T,
    /// The amount of tokens being transferred.
    pub amount: A,
    /// The address owning the tokens being transferred.
    pub from: Address,
    /// The address receiving the tokens being transferred.
    pub to: Receiver,
    /// Additional data to include in the transfer.
    /// Can be used for additional arguments.
    pub data: AdditionalData,
}

The data types are self-explanatory, but token_id is a generic type, meaning any ID type can be used. One last thing to note is that from and to can be both contract and account addresses.

#[receive(
    contract = "cis-2",
    name = "transfer",
    parameter = "TransferParameter",
    error = "ContractError",
    enable_logger,
    mutable
)]

In order to call the transfer() function, TransferParameter must provide the JSON object that includes the necessary elements of the Transfer struct.

[
    {
        "token_id": "<TOKEN-ID>",
        "amount": "<AMOUNT>",
        "from": {
            "Account": [
                "<OWNER-ADDRESS>"
            ]
        },
        "to": {
            "Account": [
                "<RECIPIENT-ADDRESS>"
            ]
        },
        "data": ""
    },
    {
        "token_id": "<TOKEN-ID>",
        "amount": "<AMOUNT>",
        "from": {
            "Account": [
                "<OWNER-ADDRESS>"
            ]
        },
        "to": {
            "Contract": [
            {
            "index": <CONTRACT-INDEX>,
            "subindex": <CONTRACT-SUBINDEX>
            },
            "onReceivingCIS2"
        ]
        },
        "data": ""
    },
]

updateOperator() and UpdateOperatorParams#

Use the updateOperator() function to assign/remove another address to act as an operator for an address. UpdateOperatorParams in updateOperator() function is an array of UpdateOperator values.

/// A single update of an operator.
#[derive(Debug, Serialize)]
pub struct UpdateOperator {
    /// The update for this operator.
    pub update: OperatorUpdate,
    /// The address which is either added or removed as an operator.
    /// Note: The address for whom this will become an operator is the sender of
    /// the contract transaction.
    pub operator: Address,
}

The OperatorUpdate (the action to execute) is either UpdateOperator::Add or UpdateOperator::Remove and the operator to either add or remove is any Address.

#[receive(
    contract = "cis-2",
    name = "updateOperator",
    parameter = "UpdateOperatorParams",
    error = "ContractError",
    enable_logger,
    mutable
)]

In order to add a contract with index 3 and subindex 0 as an operator the following JSON parameter should be used.

[
    {
        "update": {
            "Add": []
        },
        "operator": {
            "Contract": [
                {
                    "index": 3,
                    "subindex": 0
                }
            ]
        }
    }
]

balanceOf() and ContractBalanceOfQueryParams#

Use the balanceOf() function to get a balance of a token in a given address. The balanceOf() function is essentially a view function that returns ContractBalanceOfQueryResponse which is an array of the token amounts of given addresses.

#[derive(Debug, Serialize)]
pub struct BalanceOfQuery<T: IsTokenId> {
    /// The ID of the token for which to query the balance of.
    pub token_id: T,
    /// The address for which to query the balance of.
    pub address: Address,
}

ContractBalanceOfQueryParams is essentially BalanceQueryParams which is an array of BalanceQuery structs. As you can see in the details above, it accepts a generic type of token_id and a type of address like an Account or Contract.

#[receive(
    contract = "cis-2",
    name = "balanceOf",
    parameter = "ContractBalanceOfQueryParams",
    return_value = "ContractBalanceOfQueryResponse",
    error = "ContractError"
)]

In order to query the balance of account 3kBx2h5Y2veb4hZgAJWPrr8RyQESKm5TjzF3ti1QQ4VSYLwK1G of token "ff and balance of account 3kBx2h5Y2veb4hZgAJWPrr8RyQESKm5TjzF3ti1QQ4VSYLwK1G of token "aa" the following JSON parameter should be used.

[
    {
        "address": {
            "Account": [
                "3kBx2h5Y2veb4hZgAJWPrr8RyQESKm5TjzF3ti1QQ4VSYLwK1G"
            ]
        },
        "token_id": "ff"
    },
    {
        "address": {
            "Account": [
                "3kBx2h5Y2veb4hZgAJWPrr8RyQESKm5TjzF3ti1QQ4VSYLwK1G"
            ]
        },
        "token_id": "aa"
    }
]

operatorOf() and OperatorOfQueryParams#

Use the operatorOf() function to check whether an address is an operator of a given contract address added by the updateOperator(). It is a view function that returns OperatorOfQueryResponse which is an array of booleans for the given addresses (if the address is_operator() of the given contract index true, else false).

/// A query for the operator of a given address for a given token.
#[derive(Debug, Serialize)]
pub struct OperatorOfQuery {
    /// The ID of the token for which to query the balance of.
    pub owner: Address,
    /// The address for which to check for being an operator of the owner.
    pub address: Address,
}

OperatorOfQueryParams is a vector of the OperatorOfQuery struct shown above. It takes two arguments: the contract address, and the account address to check whether it is the operator or not.

#[receive(
    contract = "cis-2",
    name = "operatorOf",
    parameter = "OperatorOfQueryParams",
    return_value = "OperatorOfQueryResponse",
    error = "ContractError"
)]

In order to check whether the contract at index 3 and subindex 0 is an operator of account 3kBx2h5Y2veb4hZgAJWPrr8RyQESKm5TjzF3ti1QQ4VSYLwK1G the following JSON should be used.

[
    {
        "owner": {
            "Account": [
                "3kBx2h5Y2veb4hZgAJWPrr8RyQESKm5TjzF3ti1QQ4VSYLwK1G"
            ]
        },
        "address": {
            "Contract": [
                {
                    "index": 3,
                    "subindex":  0
                }
            ]
        }
    }
]

tokenMetadata() and ContractTokenMetadataQueryParams#

Use the tokenMetadata() function to retrieve the metadata URL of a token. It is a view function that returns a vector of TokenMetadataQueryResponse which holds a MetadataUrl struct that stores the URL and the hash.

/// The parameter type for the contract function `tokenMetadata`.
#[derive(Debug, Serialize)]
pub struct TokenMetadataQueryParams<T: IsTokenId> {
    /// List of balance queries.
    #[concordium(size_length = 2)]
    pub queries: Vec<T>,
}

ContractTokenMetadataQueryParams is an array of the TokenMetadataQueryParams struct shown above. It takes the tokenId as input, and since it is a generic type <T> the tokenId could be anything.

#[receive(
    contract = "cis-2",
    name = "tokenMetadata",
    parameter = "ContractTokenMetadataQueryParams",
    return_value = "TokenMetadataQueryResponse",
    error = "ContractError"
)]

In order to call the tokenMetadata() function, provide a JSON array of token IDs to query as shown below.

[
    "0000",
    "ffac",
    ...
]