A Extensão Metadata

Name: Token2022 com Web3.js
Availability: InStock

A extensão Metadata é uma extensão de conta Mint que introduz a capacidade de embutir metadata diretamente nas contas mint nativamente e sem precisar usar outro programa.

Inicializando a Conta Mint

A extensão Metadata é um pouco diferente do que estamos acostumados a fazer porque é composta de 2 extensões diferentes que ambas vão em uma conta Mint:

A extensão Metadata que contém toda a informação de metadata como nome, símbolo, uri e contas adicionais.
A extensão MetadataPointer que referência a conta Mint onde a extensão Metadata reside.

Normalmente, quando usadas, estas 2 extensões residem na mesma conta Mint; e vamos fazer o mesmo para este exemplo.

Vamos começar com alguns conceitos básicos antes de mergulhar no código:

Enquanto a extensão MetadataPointer reside no pacote @solana/spl-token, para inicializar o Metadata precisamos usar o pacote @solana/spl-token-metadata.

Então vamos instalar o pacote necessário:

text

npm i @solana/spl-token-metadata

Adicionalmente, a extensão Metadata é uma das "únicas" extensões que exige que você inicialize a extensão após ter inicializado a conta Mint.

Isso porque a instrução de inicialização de metadata aloca dinamicamente o espaço necessário para o conteúdo de metadata de comprimento variável.

Ao mesmo tempo, isso significa que vamos precisar inicializar a conta Mint com lamports suficientes para ser isenta de aluguel com a extensão Metadata incluída, mas alocando espaço suficiente apenas para a extensão MetadataPointer, já que a instrução token_metadata_initialize() realmente aumenta o espaço corretamente.

No código, isso fica assim:

import {
    Keypair,
    SystemProgram,
    Transaction,
    sendAndConfirmTransaction,
} from '@solana/web3.js';
import {
    createInitializeMintInstruction,
    TYPE_SIZE,
    LENGTH_SIZE,
    createInitializeMetadataPointerInstruction,
    getMintLen,
    ExtensionType,
    TOKEN_2022_PROGRAM_ID,
} from '@solana/spl-token';

import { 
    createInitializeInstruction, 
    pack, 
    TokenMetadata 
} from "@solana/spl-token-metadata";

const mint = Keypair.generate();

const metadata: TokenMetadata = {
    mint: mint.publicKey,
    name: "Test Token",
    symbol: "TST",
    uri: "https://example.com/metadata.json",
    additionalMetadata: [["customField", "customValue"]],
};

// Tamanho da conta Mint com extensões
const mintLen = getMintLen([ExtensionType.MetadataPointer]);

// Tamanho da Extensão Metadata
const metadataLen = TYPE_SIZE + LENGTH_SIZE + pack(metadata).length;

// Lamports mínimos necessários para a conta Mint
const lamports = await connection.getMinimumBalanceForRentExemption(mintLen + metadataLen);

const createAccountInstruction = SystemProgram.createAccount({
    fromPubkey: keypair.publicKey,
    newAccountPubkey: mint.publicKey,
    space: mintLen,
    lamports,
    programId: TOKEN_2022_PROGRAM_ID,
});

const initializeMetadataPointer = createInitializeMetadataPointerInstruction(
    mint.publicKey,
    keypair.publicKey,
    mint.publicKey,
    TOKEN_2022_PROGRAM_ID,
);

const initializeMintInstruction = createInitializeMintInstruction(
    mint.publicKey,
    6,
    keypair.publicKey,
    null,
    TOKEN_2022_PROGRAM_ID,
);

const initializeMetadataInstruction = createInitializeInstruction(
    {
        programId: TOKEN_2022_PROGRAM_ID,
        mint: mint.publicKey,
        metadata: mint.publicKey,
        name: metadata.name,
        symbol: metadata.symbol,
        uri: metadata.uri,
        mintAuthority: keypair.publicKey,
        updateAuthority: keypair.publicKey,
    }
);

const updateMetadataFieldInstructions = createUpdateFieldInstruction({
    metadata: mint.publicKey,
    updateAuthority: keypair.publicKey,
    programId: TOKEN_2022_PROGRAM_ID,
    field: metadata.additionalMetadata[0][0],
    value: metadata.additionalMetadata[0][1],
    });

const transaction = new Transaction().add(
    createAccountInstruction,
    initializeMetadataPointer,
    initializeMintInstruction,
    initializeMetadataInstruction,
    updateMetadataFieldInstructions,
);

const signature = await sendAndConfirmTransaction(connection, transaction, [keypair, mint]);

console.log(`Mint criada! Veja sua TX aqui: https://explorer.solana.com/tx/${signature}?cluster=devnet`);

A instrução initialize para a metadata-interface não permite additionalMetadata. Por esta razão, se queremos criar um ativo que as tenha, vamos precisar usar a instrução token_metadata_update_field() que vamos ver na próxima seção.

Atualizando a Metadata

É possível atualizar todos os campos da metadata usando a mesma instrução token_metadata_update_field().

Para o additionalMetadata isso funciona um pouco diferente porque podemos atualizar um campo existente apenas passando o mesmo Field com um novo valor ou simplesmente adicionar um novo campo ao Metadata.

Por baixo dos panos, o programa usa a mesma instrução com flag diferente baseada no que estamos tentando mudar. Isso significa que podemos mudar todos os campos assim:

const newMetadata: TokenMetadata = {
    mint: mint.publicKey,
    name: "New Name",
    symbol: "TST2",
    uri: "https://example.com/metadata2.json",
    additionalMetadata: [
        ["customField1", "customValue1"],
        ["customField2", "customValue2"],
    ],
};

// Tamanho da conta Mint com extensões
const mintLen = getMintLen([ExtensionType.MetadataPointer]);

// Tamanho da Extensão Metadata
const metadataLen = TYPE_SIZE + LENGTH_SIZE + pack(newMetadata).length;

// Lamports mínimos necessários para a conta Mint
const lamports = await connection.getMinimumBalanceForRentExemption(mintLen + metadataLen);

// Obter o saldo antigo do keypair
const oldBalance = await connection.getBalance(mint.publicKey)

console.log(`Saldo antigo: ${oldBalance}`);
console.log(`Lamports: ${lamports}`);

// Adicionar lamports à Mint se necessário para cobrir a nova isenção de aluguel da metadata
if (oldBalance < lamports) {
    const transferInstruction = SystemProgram.transfer({
        fromPubkey: keypair.publicKey,
        toPubkey: mint.publicKey,
        lamports: lamports - oldBalance,
    });

    const transaction = new Transaction().add(transferInstruction);

    const signature = await sendAndConfirmTransaction(connection, transaction, [keypair], {commitment: "finalized"});

    console.log(`Lamports adicionados à Mint! Veja sua TX aqui: https://explorer.solana.com/tx/${signature}?cluster=devnet`);
}

const updateMetadataNameInstructions = createUpdateFieldInstruction({
    metadata: mint.publicKey,
    updateAuthority: keypair.publicKey,
    programId: TOKEN_2022_PROGRAM_ID,
    field: "Name", // Field | string
    value: "New Name",
});

const updateMetadataSymbolInstructions = createUpdateFieldInstruction({
    metadata: mint.publicKey,
    updateAuthority: keypair.publicKey,
    programId: TOKEN_2022_PROGRAM_ID,
    field: "Symbol", // Field | string
    value: "TST2",
});

const updateMetadataUriInstructions = createUpdateFieldInstruction({
    metadata: mint.publicKey,
    updateAuthority: keypair.publicKey,
    programId: TOKEN_2022_PROGRAM_ID,
    field: "Uri", // Field | string
    value: "https://example.com/metadata2.json",
});

const updateMetadataAdditionalMetadataInstructions = createUpdateFieldInstruction({
    metadata: mint.publicKey,
    updateAuthority: keypair.publicKey,
    programId: TOKEN_2022_PROGRAM_ID,
    field: "customField2", // Field | string
    value: "customValue2",
});

const transaction = new Transaction().add(
    updateMetadataNameInstructions,
    updateMetadataSymbolInstructions,
    updateMetadataUriInstructions,
    updateMetadataAdditionalMetadataInstructions,
);

const signature = await sendAndConfirmTransaction(connection, transaction, [keypair]);

console.log(`Metadata atualizada! Veja sua TX aqui: https://explorer.solana.com/tx/${signature}?cluster=devnet`);

Como você pode ver, sempre precisamos ter certeza de que a conta está isenta de aluguel, é por isso que fazemos todos os cálculos de aluguel no início e transferimos lamports adicionais se necessário.

Podemos remover Field na struct additionalMetadata também usando a instrução RemoveKey assim:

const removeMetadataKeyInstructions = createRemoveKeyInstruction({
    metadata: mint.publicKey,
    updateAuthority: keypair.publicKey,
    programId: TOKEN_2022_PROGRAM_ID,
    key: "customField", // Field | string
    idempotent: true,
});