This tutorial shows how to delete an account from the XRP Ledger, including checking that it meets the requirements for deletion.
By following this tutorial, you should learn how to:
- Check if an account can be deleted.
- Delete an account.
To complete this tutorial, you should:
- Have a basic understanding of the XRP Ledger.
- Have an XRP Ledger client library, such as xrpl.js, installed.
- Have an XRP Ledger Testnet account to delete. If you create a new account as part of the tutorial, you must wait about 15 minutes for it to become eligible for deletion.
- Know an address where you want to send the deleted account's remaining XRP. For this tutorial, you can use the address
rJjHYTCPpNA3qAM8ZpCDtip3a8xg7B8PFoto return funds to the Testnet faucet.
From the code sample folder, use npm to install dependencies:
npm iTo get started, import the client library and instantiate an API client. To delete an account, you need the address of an account to receive the deleted account's remaining XRP.
The sample code also imports dotenv so that it can load environment variables from a .env file.
import { Client, Wallet, getBalanceChanges, validate } from 'xrpl'
import 'dotenv/config'
const client = new Client('wss://s.altnet.rippletest.net:51233')
await client.connect()
// Where to send the deleted account's remaining XRP:
const DESTINATION_ACCOUNT = 'rJjHYTCPpNA3qAM8ZpCDtip3a8xg7B8PFo' // Testnet faucetYou need to instantiate a wallet instance for the account you want to delete. Since you can only delete an account that is at least ~15 minutes old, the sample code loads a seed value from a .env file. If you don't have an account seed defined in the .env file, you can get a new account from the faucet, but it won't be possible to delete it right away.
// Load the account to delete from .env file -----------------------------------
// If the seed value is still the default, get a new account from the faucet.
// It won't be deletable immediately.
let wallet
if (!process.env.ACCOUNT_SEED || process.env.ACCOUNT_SEED === 's████████████████████████████') {
console.log("Couldn't load seed from .env; getting account from the faucet.")
wallet = (await client.fundWallet()).wallet
console.log(`Got new account from faucet:
Address: ${wallet.address}
Seed: ${wallet.seed}
`)
console.log('Edit the .env file to add this seed, then wait until the account can be deleted.')
} else {
wallet = Wallet.fromSeed(process.env.ACCOUNT_SEED, { algorithm: process.env.ACCOUNT_ALGORITHM })
console.log(`Loaded account: ${wallet.address}`)
}Before deleting an account, you should check that it meets the requirements for deletion.
The first step to checking if an account can be deleted is to get its account info as of the latest validated ledger.
// Check account info to see if account can be deleted -------------------------
let acctInfoResp
try {
acctInfoResp = await client.request({
command: 'account_info',
account: wallet.address,
ledger_index: 'validated'
})
} catch (err) {
console.error('account_info failed with error:', err)
client.disconnect()
process.exit(1)
}
let numProblems = 0Check that the account's current sequence number, in the Sequence field of the account data, is low enough compared with the latest validated ledger index. For the account to be deletable, its sequence number plus 255 must be lower than or equal to the ledger index.
// Check if sequence number is too high
const acctSeq = acctInfoResp.result.account_data.Sequence
const lastValidatedLedgerIndex = acctInfoResp.result.ledger_index
if (acctSeq + 255 > lastValidatedLedgerIndex) {
console.error(`Account is too new to be deleted.
Account sequence + 255: ${acctSeq + 255}
Validated ledger index: ${lastValidatedLedgerIndex}
(Sequence + 255 must be less than or equal to the ledger index)`)
// Estimate time until deletability assuming ledgers close every ~3.5 seconds
const estWaitTimeS = (acctSeq + 255 - lastValidatedLedgerIndex) * 3.5
if (estWaitTimeS < 120) {
console.log(`Estimate: ${estWaitTimeS} seconds until account can be deleted`)
} else {
const estWaitTimeM = Math.round(estWaitTimeS / 60, 0)
console.log(`Estimate: ${estWaitTimeM} minutes until account can be deleted`)
}
numProblems += 1
} else {
console.log(`OK: Account sequence number (${acctSeq}) is low enough.`)
}Check the OwnerCount field of the account data to see if the account owns too many other ledger entries. For an account to be deletable, it must own 1000 or fewer entries (of any type) in the ledger.
// Check if owner count is too high
const ownerCount = acctInfoResp.result.account_data.OwnerCount
if (ownerCount > 1000) {
console.error(`Account owns too many objects in the ledger.
Owner count: ${ownerCount}
(Must be 1000 or less)`)
numProblems += 1
} else {
console.log(`OK: Account owner count (${ownerCount}) is low enough.`)
}Deleting an account requires a special transaction cost equal to the incremental owner reserve, so an account can't be deleted if its current XRP balance is less than that. To check if an account has enough XRP, use the server_state method to look up the current incremental reserve and compare with the account's XRP balance in the Balance field of the account data.
Balance field is in drops of XRP. Be sure to compare equivalent units! (1 XRP = 1 million drops)// Check if XRP balance is high enough
// Look up current incremental owner reserve to compare vs account's XRP balance
// using server_state so that both are in drops
let serverStateResp
try {
serverStateResp = await client.request({
command: 'server_state'
})
} catch (err) {
console.error('server_state failed with error:', err)
client.disconnect()
process.exit(1)
}
const deletionCost = serverStateResp.result.state.validated_ledger?.reserve_inc
if (!deletionCost) {
console.error("Couldn't get reserve values from server. " +
"Maybe it's not synced to the network?")
client.disconnect()
process.exit(1)
}
const acctBalance = acctInfoResp.result.account_data.Balance
if (acctBalance < deletionCost) {
console.error(`Account does not have enough XRP to pay the cost of deletion.
Balance: ${acctBalance}
Cost of account deletion: ${deletionCost}`)
numProblems += 1
} else {
console.log(`OK: Account balance (${acctBalance} drops) is high enough.`)
}Check the FirstNFTokenSequence and MintedNFTokens fields of the account. (If either field is absent, you can treat its value as 0 for this purpose.) For the account to be deletable, the sum of these two numbers plus 255 must be lower than or equal to the current ledger index.
// Check if FirstNFTSequence is too high
const firstNFTSeq = acctInfoResp.result.account_data.FirstNFTokenSequence || 0
const mintedNFTs = acctInfoResp.result.account_data.MintedNFTokens || 0
if (firstNFTSeq + mintedNFTs + 255 > lastValidatedLedgerIndex) {
console.error(`Account's FirstNFTokenSequence + MintedNFTokens + 255 is too high.
Current total: ${firstNFTSeq + mintedNFTs + 255}
Validated ledger index: ${lastValidatedLedgerIndex}
(FirstNFTokenSequence + MintedNFTokens + 255 must be less than or equal to the ledger index)`)
numProblems += 1
} else {
console.log('OK: FirstNFTokenSequence + MintedNFTokens is low enough.')
}If the account has issued any NFTs that are still present in the ledger, the account cannot be deleted. You can check to see if any exist by comparing the MintedNFTokens field and BurnedNFTokens fields of the account. (In both cases, if the field is omitted, treat its value as 0.) If the MintedNFTokens value is larger, the account has issued at least one NFT that has not been burned yet.
// Check that all issued NFTs have been burned
const burnedNFTs = acctInfoResp.result.account_data.BurnedNFTokens || 0
if (mintedNFTs > burnedNFTs) {
console.error(`Account has issued NFTs outstanding.
Number of NFTs minted: ${mintedNFTs}
Number of NFTs burned: ${burnedNFTs}`)
numProblems += 1
} else {
console.log('OK: No outstanding, un-burned NFTs')
}If any of the previous checks failed, you can't delete the account. Resolving the problems varies by type:
- If the account sequence or NFT sequence number is too low, wait for the ledger index to advance automatically and try again later. About 15 minutes should be enough.
- If the account owns too many objects, or has issued NFTs outstanding, remove the offending objects.
- If the account does not have enough XRP, you can send XRP to it so that it can pay the deletion cost, but of course in this case the account does not have enough XRP for you to recover any by deleting it. You can also wait and try again if the network votes to lower the reserve requirements, which would also lower the cost to delete an account.
The sample code does not try to handle these problems, and quits if any problems were found:
// Stop if any problems were found
if (numProblems) {
console.error(`A total of ${numProblems} problem(s) prevent the account from being deleted.`)
client.disconnect()
process.exit(1)
}Some types of ledger entries can block an account from being deleted. You can check for these types of entries using the account_objects method with the "deletion_blockers_only": true parameter.
// Check for deletion blockers -------------------------------------------------
const blockers = []
let marker
const ledger_index = 'validated'
while (true) {
let accountObjResp
try {
accountObjResp = await client.request({
command: 'account_objects',
account: wallet.address,
deletion_blockers_only: true,
ledger_index,
marker
})
} catch (err) {
console.error('account_objects failed with error:', err)
client.disconnect()
process.exit(1)
}
for (const obj of accountObjResp.result.account_objects) {
blockers.push(obj)
}
if (accountObjResp.result.marker) {
marker = accountObjResp.result.marker
} else {
break
}
}
if (!blockers.length) {
console.log('OK: Account has no deletion blockers.')
} else {
console.log(`Account cannot be deleted until ${blockers.length} blocker(s) are removed:`)
for (const blocker of blockers) {
console.log(JSON.stringify(blocker, null, 2))
}
client.disconnect()
process.exit(1)
}If the account has deletion blockers, you may or may not be able to remove them by sending other transactions, depending on the ledger entry. For example, if one of the blockers is a RippleState entry, you may be able to remove it by reducing your balance to zero through payments or offers and using a TrustSet transaction to return your settings to the default state. Since there are many possibilities, the sample code does not show how to remove deletion blockers.
If all the checks passed, send an AccountDelete transaction to delete the account. Since this transaction type requires a much higher transaction cost than normal, it's a good idea to submit the transaction with the "fail hard" setting enabled. This can save you from paying the transaction cost if the transaction was going to fail with a tec result code. (Fail hard stops the server from relaying the transaction to the network if the transaction provisionally fails, which catches common errors before the transaction can achieve a consensus.)
// Delete the account ----------------------------------------------------------
const accountDeleteTx = {
TransactionType: 'AccountDelete',
Account: wallet.address,
Destination: DESTINATION_ACCOUNT
}
validate(accountDeleteTx)
console.log('Signing and submitting the AccountDelete transaction:',
JSON.stringify(accountDeleteTx, null, 2))
const deleteTxResponse = await client.submitAndWait(accountDeleteTx, { wallet, autofill: true, failHard: true })If the transaction is successful, you can use getBalanceChanges(...) to check the metadata and see how much XRP was delivered from the deleted account to the destination account.
// Check result of the AccountDelete transaction -------------------------------
console.log(JSON.stringify(deleteTxResponse.result, null, 2))
const resultCode = deleteTxResponse.result.meta.TransactionResult
if (resultCode !== 'tesSUCCESS') {
console.error(`AccountDelete failed with code ${resultCode}.`)
client.disconnect()
process.exit(1)
}
console.log('Account deleted successfully.')
const balanceChanges = getBalanceChanges(deleteTxResponse.result.meta)
console.log('Balance changes:', JSON.stringify(balanceChanges, null, 2))
client.disconnect()