Subname Transactions

caution

The examples on this page use SuinsClient. @mysten/suins 2.0 still exports it, but the suins() client extension is the preferred pattern. The SuinsTransaction commands themselves are unchanged, but the client you pass them is constructed differently. See Migrating @mysten/suins.

The following subname-related PTB commands are available through the SDK. For name registration, renewal, and other operations, see Building Transactions.

Create a subname

const createSubname = async (subName: string, parentNftId: string, expirationMs: number) => {
    // Create a transaction block as usual in your PTBs.
    const transaction = new Transaction();
    // Pass in the transaction block & the app's global SuinsClient.
    const suinsTransaction = new SuinsTransaction(suinsClient, transaction);

    // We build the transaction to create a subname.
	const subNameNft = suinsTransaction.createSubName({
        // The NFT of the parent
        parentNft: parentNftId,
        // The subname to be created.
        name: subName,
        // The expiration timestamp needs to be less than or equal to the parent's expiration.
        expirationTimestampMs: expirationMs,
        // Whether the subname can create more nested subnames.
        // E.g. more.inner.sui could create even.more.inner.sui
        allowChildCreation: true,
        // Whether the subname can manually extend the expiration time to
        // the expiration time of the parent name. Can be tweaked after creation too.
        allowTimeExtension: true,
    });

    // Transfer the NFT
    transaction.transferObjects([subNameNft], transaction.pure.address('0xMyAddress'));
    // ... sign and execute the transaction
}

Edit subname setup

Allows the parent holder to edit the setup (allow child creation and allow time extension) for a subname.

const editSetup = async (name: string, parentNftId: string, allowChildCreation: boolean, allowTimeExtension: boolean) => {
    // Create a transaction block as usual in your PTBs.
    const transaction = new Transaction();
    // Pass in the transaction block & the app's global SuinsClient.
    const suinsTransaction = new SuinsTransaction(suinsClient, transaction);

    // We build the transaction to edit the setup of a subname.
    suinsTransaction.editSetup({
        name,
        parentNft: parentNftId,
        allowChildCreation,
        allowTimeExtension,
    });

    // ... sign and execute the transaction
}

Extend a subname's expiration

You can use this functionality only if the parent allows time extension for the subname.

const extendExpiration = async (nftId: string, expirationMs: number) => {
    // Create a transaction block as usual in your PTBs.
    const transaction = new Transaction();
    // Pass in the transaction block & the app's global SuinsClient.
    const suinsTransaction = new SuinsTransaction(suinsClient, transaction);

    // We build the transaction to extend the expiration of a subname.
    suinsTransaction.extendExpiration({
        nft: nftId,
        expirationTimestampMs: expirationMs,
    });

    // ... sign and execute the transaction
}

Create a leaf subname

Read more about the differences between a subname and a leaf subname.

const createLeafSubname = async (name: string, parentNftId: string, targetAddress: string) => {
    // Create a transaction block as usual in your PTBs.
    const transaction = new Transaction();
    // Pass in the transaction block & the app's global SuinsClient.
    const suinsTransaction = new SuinsTransaction(suinsClient, transaction);

    // We build the transaction to create a leaf subname.
    // A leaf subname is a subname that has a target address and no NFT of its own.
    suinsTransaction.createLeafSubName({
        // The NFT of the parent
        parentNft: parentNftId,
        // The leaf subname to be created.
        name,
        // the target address of the leaf subname (any valid Sui address)
        targetAddress
    });

    // ... sign and execute the transaction
}

Remove a leaf subname

const removeLeafSubname = async (name: string, parentNftId: string) => {
    // Create a transaction block as usual in your PTBs.
    const transaction = new Transaction();
    // Pass in the transaction block & the app's global SuinsClient.
    const suinsTransaction = new SuinsTransaction(suinsClient, transaction);

    // Build the transaction to remove a leaf subname.
    suinsTransaction.removeLeafSubName({
        // The NFT of the parent
        parentNft: parentNftId,
        // The leaf subname to be removed.
        name,
    });

    // ... sign and execute the transaction
}