Sui

Mysten / SUI

Mysten (Sui) can be accessed with the following coin types:

Environment	Coin Type	Faucet
Sui Production	sui
Sui Testnet	tsui	https://docs.sui.io/guides/developer/getting-started/get-coins

Overview

Mysten is a protocol created by former Meta employees. The native asset of the Mysten protocol is Sui. It is an object based protocol, almost UTXO like. We support MPC transactions on SUI.

Explorer

https://suiexplorer.com/

Generating Wallets

To create an Sui wallet using BitGoJS:

Copy code block
1
2
3
4
5
6
7
8
9
10
11
12
13
bitgo
  .coin('tsui')
  .wallets()
  .generateWallet({
    label: 'My Test Wallet',
    passphrase: 'secretpassphrase1a5df8380e0e30',
    multisigType: 'tss',
    enterprise: '234578765432'
  })
  .then(function (wallet) {
    // print the new wallet
    console.dir(wallet);
  });

To create a Sui wallet using the platform API:

Copy code block
1
2
3
4
5
6
7
8
9
LABEL="My Test Wallet"
PASSPHRASE="secretpassphrase1a5df8380e0e30"
MULTISIG="tss"

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d "{ \"label\": \"$LABEL\", \"passphrase\": \"$PASSPHRASE\",  \"multisigType\": \"$MULTISIG\" }" \
http://$BITGO_EXPRESS_HOST/api/v2/tsui/wallet/generate

Staking

For Mysten there is a minimum requirement to stake 1 SUI. After initiating the staking request, there's a warmup period of 1 epoch, and a cooldown period of 1 epoch when you decide to unstake. When deciding to unstake, you must unstake the entire SUI object.

Rewards are automatically compounded.

Receive addresses

SUI has no minimum balance for receive addresses. However, at least 1 SUI is required in each receive address to consolidate token balances to the base address.

In order to create a receive address:

Copy code block
1
2
3
4
5
6
7
8
9
10
11
bitgo
  .coin('tsui')
  .wallets()
  .getWallet({ id: '585c51a5df8380e0e3082e46' })
  .then(function (wallet) {
    return wallet.createAddress();
  })
  .then(function (newAddress) {
    // print new address details
    console.dir(newAddress);
  });

Copy code block
1
2
3
4
5
WALLET=585c51a5df8380e0e3082e46

curl -X POST \
-H "Authorization: Bearer $ACCESS_TOKEN" \
https://app.bitgo-test.com/api/v2/tsui/wallet/$WALLET/address

Transactions

SUI uses overall object modeling, which is similar to the UTXO model. With SUI, storage is centered around objects. Transactions take objects as input and output new or mutated objects.

You can make use of sendMany() to send transactions. It's also important to note that while SUI does support batch transactions, these cannot be run sequentially. For the batch transactions, you'll need to wait for each to be confirmed on chain before submitting another. If you want to run a series of transactions, it's better to use sendMany.

When sending SUI, you'll need to account for the fact that the base unit of SUI has 9 decimal places (1 SUI = 1000000000 MYST).

Copy code block
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
const recipients = [{
  address: 'sui-address-1',
  amount: '10000000000',
},
{
  address: 'sui-address-2',
  amount: '200000000000',
}];

bitgo.authenticateWithAccessToken({ accessToken });
bitgo.unlock({otp: '000000'})
const wallet = await bitgo.coin(coin).wallets().getWallet({ id: walletId });


const response = await wallet.sendMany({
    recipients,
    passphrase,
    type: 'transfer'
});

Gas fees

A SUI transaction must pay a gas fee. SUI's Gas Pricing Mechanism ensures that any transaction pays fees according to both computational and storage costs.

A gas budget must be submitted with a SUI transaction. Gas budgets provide a limit to the amount of gas fees a user will pay. For more, see Gas in Sui.

Estimate Gas Fees in Sui

The gas fee is variable and differs from transaction to transaction. There's no way to get a precise fee estimate before a transaction. The fee estimate is composed of 3 components: computation cost, storage cost, and storage rebate. While the computation cost remains relatively constant, the storage cost and storage rebate can vary significantly.

Sui also has a concept of negative gas fees. If you overpay for a transaction, the excess gas fees are returned to you. This system promotes users to optimize storage usage on the blockchain, promoting cost efficiency and contributing to the efficient operation of the Sui network. However, this also makes predicting transaction fees more challenging.

Pre-build a transaction and generate an unsigned hex that you can use to obtain a fee estimate by running this script. This script, when run, will log a transaction hex. You can then pass this value to BitGo's API to receive a fee estimate.

Running the script

First, run yarn install from the root directory of the repository.

Then change into the examples/ts/sui directory and use npx ts-node to run it:

Copy code block
1
2
 cd examples/ts/sui/
 npx ts-node get-transaction-hex.ts

Note

• Ensure your wallet ID and passphrase are correct.
• Replace placeholder values with actual data from your BitGo account.

Expected Output

The output should be as follows:

Copy code block
1
2
Required tx param:
AAACAAgQJwAAAAAAAAAgWi8a831WVBkJYTbreVK3NAIGZI%2BhQCuftQI4dx1DSicCAgABAQAAAQECAAABAQDojrUgsPIyDtSTV6rS54xejLr67f2B%2B%2F159oq6evGnEwHu2GGYi3WJarkc27zGeL7%2FDmtIWy6IKEI5Uy6sGolMV1LgwAAAAAAAII2Sh%2FcsCB2AGmMSpi%2Bu65igNCuTAeYQ1ionZjpcAkBv6I61ILDyMg7Uk1eq0ueMXoy6%2Bu39gfv9efaKunrxpxPoAwAAAAAAAKSIIQAAAAAAAA%3D%3D

Copy this value and use it as a parameter in this URL:

Copy code block
1
https://app.bitgo-test.com/api/v2/tsui/tx/fee?tx=<tx-value>

The fee estimate result should look like this:

Copy code block
1
2
3
4
5
6
{
  "feeEstimate": "3954120",
  "computationCost": "1000000",
  "storageCost": "1976000",
  "storageRebate": "978120"
}

Gas Tank (Fee Sponsorship)

BitGo uses a Gas Tank to pay for transaction fees on Sui. This setup enables fee sponsorship—meaning that for enterprises with Gas Tank enabled, the Gas Tank pays all transaction fees on behalf of their users' wallets.

Key Benefits

• Centralized fee management: All fees are paid from a single enterprise-controlled address
• Gasless transactions for users: End users can send SUI and tokens without holding native SUI for gas
• Improved user experience: Seamless transactions without worrying about gas balances

Enabling Fee Sponsorship

Fee sponsorship for Sui is enabled at the enterprise level. To request enablement, reach out to BitGo support. Once enabled, fee sponsorship applies to all wallets under that enterprise — you cannot opt in or out on a per-wallet or per-transaction basis.

Scope

Each enterprise has a single shared gas tank (fee address). All wallets under the enterprise share this gas tank. When any wallet in the enterprise sends a transaction, the gas tank is used to cover fees. Plan your gas tank funding based on the aggregate transaction volume across all wallets.

How to Fund the Gas Tank

To fund your gas tank, send SUI to the gas tank address. You can retrieve the gas tank address using the Get Fee Address Balance endpoint (see the Check Gas Tank Balance section below). Simply transfer SUI to the returned address from any external wallet or exchange. For more details, see Fund Gas Tanks.

Without Fee Sponsorship

If your enterprise does not have fee sponsorship enabled, the sender wallet pays all transaction fees directly from its own balance. In this case:

• For native SUI transfers, the transaction fee is deducted from the sender wallet (transfer amount + gas).
• For token transfers, the sender wallet must hold enough SUI to cover the gas fee.
• No gas tank is involved; the sender wallet must have sufficient SUI for every transaction.

What Can Be Sponsored

Transaction Type	What Gas Tank Pays
Consolidation	Transaction fee (all gas costs)
Native SUI Transfer	Transaction fee (all gas costs)
Token Transfer	Transaction fee (all gas costs)

Sponsorship Models

Native SUI Transfer

When sending SUI from a wallet from an enterprise with fee sponsorship enabled:

Component	Paid By
Recipient Amount	Sender Wallet
Transaction Fee (Gas)	Gas Tank

The sender wallet only needs sufficient SUI for the transfer amount. The gas tank pays all computation, storage, and gas costs.

Token Transfer

For token transfers, the gas tank pays all transaction fees. The sender wallet provides the tokens to send.

Component	Paid By
Token Amount	Sender Wallet
Transaction Fee (Gas)	Gas Tank

Consolidation

When consolidating objects from multiple receive addresses:

Component	Paid By
Consolidated Amount	Sent to root address
Transaction Fee (Gas)	Gas Tank

With fee sponsorship, users can consolidate their entire balance without reserving SUI for gas. The gas tank covers all fees.

Minimum Gas Tank Balance Requirements

The gas tank must hold a minimum amount of SUI for each transaction type. Unlike UTXO model, Sui uses an object-based model where each object must meet minimum requirements.

Transaction Type	Minimum Gas Tank Balance	Breakdown
Any Transaction	0.1 SUI per object	Minimum object size for gas payment

Object-Based Architecture:

Sui uses objects rather than UTXOs. Each SUI coin is represented as an object with a unique objectId, version, and digest. For gas payments, the gas tank must have objects of at least 0.1 SUI each.

Example: If your gas tank holds 1.0 SUI, BitGo automatically splits it into multiple objects of 0.1 SUI each (after reserving 0.2 SUI as a buffer), enabling parallel transaction processing.

Note: If the gas tank has insufficient SUI or no available objects >= 0.1 SUI, the transaction will fail with the error Insufficient tsui utxo found on the gas tank, Please transfer 0.1 tsui to the address to allow withdrawal.

Concurrency and Throughput

Because Sui uses an object-based model similar to the UTXO model, each concurrent transaction requires its own gas object. This means the number of transactions you can process in parallel is limited by the number of available objects in your gas tank.

Example: If your gas tank holds 1.0 SUI, BitGo's internal split logic can create approximately 8 objects of 0.1 SUI each (after reserving 0.2 SUI buffer). That gives you capacity for up to 8 concurrent transactions in one round.

After each transaction, the remaining gas from that object becomes available again for subsequent transactions (subject to object availability and timing).

To increase throughput:

• Fund your gas tank with more SUI to create more objects via automatic splitting
• Larger gas tank balance = more objects = more concurrent transactions

Gas Tank Depletion

If the gas tank runs out of SUI (or available objects) while processing transactions:

• Pending transactions that have already reserved objects will continue to process normally.
• New transactions will fail immediately with the error Insufficient tsui utxo found on the gas tank, Please transfer 0.1 tsui to the address to allow withdrawal. They will not be queued or retried automatically.
• To resume operations, fund the gas tank with additional SUI. Once the deposit is confirmed on-chain and automatically split into objects, new transactions can proceed.

Automatic Object Splitting

Unlike traditional account-based blockchains, Sui uses an object-based model. BitGo automatically optimizes your gas tank by splitting large deposits into smaller objects for efficient transaction building.

When your gas tank receives a deposit exceeding 0.1 SUI, BitGo automatically:

1. Detects the large deposit
2. Triggers a system-initiated split transaction
3. Creates multiple 0.1 SUI objects
4. Repeats if necessary until the entire deposit is fully split

Parameter	Value
Fee Buffer	0.2 SUI
Max Outputs	100 per split
Min Outputs	2
Object Size	0.1 SUI
Split Trigger	>=0.1 SUI

Cascading Split Transactions

Due to Sui's protocol-level restrictions on maximum transaction size (max 255 gas payment objects), a single split transaction can only produce a limited number of output objects. If the deposit is large, BitGo will create multiple cascading split transactions — each transaction splits a portion of the remaining balance, and any leftover amount triggers another split transaction automatically. This process continues until the entire deposited amount has been split into 0.1 SUI objects.

Example: You deposit 20.0 SUI into the gas tank.

When you deposit 20.0 SUI, BitGo automatically splits it into multiple 0.1 SUI objects to enable parallel transaction processing:

1. Split transaction 1:

   • Takes the 20.0 SUI deposit
   • Reserves 0.2 SUI as buffer for transaction fees
   • Splits the remaining balance into 0.1 SUI objects (up to 100 outputs per transaction)
   • Creates a remainder object if more splitting is needed
   • Status: ✅ Confirmed on-chain

2. Split transaction 2 (triggered automatically if remainder exceeds 0.1 SUI):

   • Takes the remainder object from split 1
   • Continues splitting into 0.1 SUI objects
   • Reserves buffer for fees
   • Status: ✅ Confirmed on-chain

Final Result:

• The 20 SUI deposit is split into approximately 196-197 objects of 0.1 SUI each
• Small buffer retained for transaction fees
• Concurrent transaction capacity: ~196-197 parallel transactions

This means after depositing 20 SUI, your gas tank can process approximately 196-197 concurrent transactions in parallel, with each transaction consuming one 0.1 SUI gas object.

Note: These are system-initiated transactions that appear on-chain and in your transaction history. They are not user-initiated and require no action on your part. During the splitting process, the objects being split are temporarily unavailable for other transactions. Once splitting completes, all resulting 0.1 SUI objects become available for concurrent transaction processing.

This optimization:

• Enables parallel transaction processing
• Reduces object contention during high-volume operations
• Requires no manual intervention

Transaction Flow

When a sponsored transaction is executed:

1. User initiates a transaction (withdrawal, token transfer, or consolidation) from their wallet via the API or SDK.
2. BitGo selects objects from the sender wallet for the transaction amount.
3. BitGo selects objects from the gas tank for gas payment (minimum 0.1 SUI per object).
4. Selected objects from both the sender and gas tank are reserved to prevent double-spending. Reserved objects cannot be used by other concurrent transactions.
5. Transaction is built with both sender and gas tank inputs.
6. Transaction is signed by both the user and the gas tank (dual signature).
7. Transaction is broadcasted to the Sui network.
8. Upon confirmation (or failure), the reserved objects are released.

Object Reservation Lifecycle

When objects are reserved during step 4, they follow this lifecycle:

• On success: Objects are consumed by the confirmed transaction. New objects are created for the sender (change) and gas tank (remaining gas).
• On failure or cancellation: Objects are unreserved immediately and become available for new transactions.
• On timeout (no response): If a transaction is neither confirmed nor explicitly cancelled, the reservation automatically expires after 7 days (the reservation TTL). This is a safety net to prevent objects from being permanently locked due to edge cases like network issues. Under normal operation, you should not encounter this 7-day wait.

Check Gas Tank Balance

Endpoints:

• Get Fee Address Balance

Copy code block
1
2
3
4
5
6
7
8
export COIN="tsui"
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"

curl -X GET \
  https://app.bitgo-test.com/api/v2/$COIN/enterprise/$ENTERPRISE_ID/feeAddressBalance \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Step Result

Copy code block
1
2
3
4
{
  "balance": "1000000000",
  "address": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}

Best Practices

1. Monitor Gas Tank Balance: Ensure gas tank always has sufficient SUI (multiple 0.1 SUI objects for concurrency)
2. Plan for Concurrent Transactions: Each concurrent transaction requires one gas object (0.1 SUI minimum)
3. Automatic Splitting: Large deposits (>0.1 SUI) are automatically split—no manual intervention required
4. Buffer Management: BitGo reserves 0.2 SUI as a buffer during splits to ensure gas availability

Troubleshooting

Error	Cause	Resolution
Failed to acquire lock	All gas tank objects are reserved by concurrent transactions	Retry the request after a short delay. If this happens frequently, fund the gas tank with more SUI to increase the number of available objects.
Insufficient balance in gas tank	Gas tank has insufficient SUI or no available objects >= 0.1 SUI	Fund the gas tank with more SUI. Ensure at least 0.1 SUI is available. BitGo will automatically split large deposits into usable objects.
Objects stuck in reserved state	Transaction did not complete or fail properly	Reserved objects automatically expire after 7 days. If immediate resolution is needed, contact BitGo support.