Building Transactions

SuinsTransaction is the client used similar to Transaction, and helps in building a transaction. You need to instatiate it once in every programmable transaction block (PTB) that you're building.

Available functions

Here's a list of all the available PTB commands supported through the SDK.

Registering a name

 
const register = async (name: string, years: number) => {
    // Query the latest price list from the chain.
    const priceList = await suinsClient.getPriceList();
    // 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 register the name.
	const nft = suinsTransaction.register({
		name,
		years,
		price: suinsClient.calculatePrice({ name, years, priceList }),
	});
 
    // Transfer the name's NFT
    transaction.transferObjects([nft], transaction.pure.address('0xMyAddress'));
 
    // ... sign and execute the transaction
}

Renewing a name

const renew = async (nftId: string, name: string, years: number) => {
    // Query the latest pricelist from the chain.
    const priceList = await suinsClient.getRenewalPriceList();
    // 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 renew the name.
    suinsTransaction.renew({
        nftId,
        years,
        price: suinsClient.calculatePrice({ name, years, priceList }),
    });
 
    // ... sign and execute the transaction
}

Setting a name's target address

This works the same for names and subnames.

const setTargetAddress = async (nftId: string, address: 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 set the target address.
    suinsTransaction.setTargetAddress({
        nftId,
        address,
        isSubname: false,
    });
 
    // ... sign and execute the transaction
}

Setting a name as default

This works the same for names and subnames.

const setDefault = async (name: 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 set that name as default for the sender.
    // Important: This is only possible if the address signing/executing
    // the transaction is the same as the target address of that name.
    suinsTransaction.setDefault(name);
 
    // ... sign and execute the transaction
}

Creating 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
}

Editing Subname's setup

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

const editSetup = async (name: stringify, 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
}

Extending a Subname's expiration

This functionality is available 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
}

Creating a leaf subname

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

const createLeafSubname = async (name: stringify, 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
}

Removing 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
}

Setting a name's metadata

Currently supports AVATAR and IPFS hash.

const setMetadata = async (nft: string, avatar: string, contentHash: 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 set the metadata.
    // Set the avatar to the supplied value.
    suinsTransaction.setMetadata({
        nft,
        key: ALLOWED_METADATA.avatar,
        value: avatar
    });
    // Set the contentHash to the supplied value.
    suinsTransaction.setMetadata({
        nft,
        key: ALLOWED_METADATA.contentHash,
        value: contentHash
    });
 
    // ... sign and execute the transaction
}

Burning an expired name

Allows burning an expired name to get back storage rebates.

const burn = async (nftId: 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 burn the expired name.
    suinsTransaction.burn({
        nft: nftId,
        // Whether it's a subname.
        isSubname: false,
    });
 
    // ... sign and execute the transaction
}

Combined example

The following code snippet registers a SuiNS name, sets its target address, and sets it as the default name for the target address in a single PTB. You could also add transaction commands to do even more in the same PTB if you wanted to, like create subnames and so on, but that is beyond the scope of this example.

// Years must be between 1-5.
const composedExample = async (name: string, years: number) => {
    // Query the latest price list from the chain.
    const priceList = await suinsClient.getPriceList();
    
    // 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 register the name.
	const nft = suinsTransaction.register({
		name,
		years,
		price: suinsClient.calculatePrice({ name, years, priceList }),
	});
 
    // You can now use this NFT, for instance to set its target address.
	suinsTransaction.setTargetAddress({
		nft,
		address: '0xMyAddress',
	});
 
    // And you could also set this name as the default name for `0xMyAddress`.
    // This is only possible if the address signs and executes the transaction.
	suinsTransaction.setDefault(name);
 
    // Transfer the name's NFT to the address.
    transaction.transferObjects([nft], transaction.pure.address('0xMyAddress'));
 
    // ... sign and execute the transaction
}

Querying Examples