DeleteAttempts

DeleteAttempts removes terminal (settled or failed) payment attempt records from the server's attempt store. The client explicitly names the attempt IDs to delete, enabling online garbage collection of completed attempt data.

The server processes each attempt ID independently and reports per-ID results. Pending (in-flight) attempts are never deleted; they are reported with a DELETION_PENDING status. Unknown attempt IDs are reported with DELETION_NOT_FOUND. Unprocessable records are reported with DELETION_FAILED. The overall RPC succeeds (gRPC OK) as long as the request could be processed, even if individual attempts were not deleted.

Clients MUST only delete attempts whose outcome (settled or failed) has been durably recorded and will never need to be retried. Deleting an attempt removes the server's idempotency protection for that attempt ID.

Source: switchrpc/switch.proto

gRPC

rpc DeleteAttempts (DeleteAttemptsRequest) returns (DeleteAttemptsResponse);

REST

HTTP Method	Path
POST	/v2/switch/deleteattempts

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:10009'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
const TLS_PATH = 'LND_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync(['lightning.proto', 'switchrpc/switch.proto'], loaderOptions);
const switchrpc = grpc.loadPackageDefinition(packageDefinition).switchrpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
const macaroon = fs.readFileSync(MACAROON_PATH).toString('hex');
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
  let metadata = new grpc.Metadata();
  metadata.add('macaroon', macaroon);
  callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let client = new switchrpc.Switch(GRPC_HOST, creds);
let request = {
  attempt_ids: <uint64>,
};
client.deleteAttempts(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "results": <AttemptDeletionResult>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the switchrpc/switch.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import switch_pb2 as switchrpc, switch_pb2_grpc as switchstub

GRPC_HOST = 'localhost:10009'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

# create macaroon credentials
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
def metadata_callback(context, callback):
  callback([('macaroon', macaroon)], None)
auth_creds = grpc.metadata_call_credentials(metadata_callback)
# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# combine macaroon and SSL credentials
combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)
# make the request
channel = grpc.secure_channel(GRPC_HOST, combined_creds)
stub = switchstub.SwitchStub(channel)
request = switchrpc.DeleteAttemptsRequest(
  attempt_ids=<uint64>,
)
response = stub.DeleteAttempts(request)
print(response)
# {
#    "results": <AttemptDeletionResult>,
# }

grpcurl

# grpcurl docs: https://github.com/fullstorydev/grpcurl
# Proto source: https://github.com/lightningnetwork/lnd
GRPC_HOST=localhost:10009
LND_DIR=~/.lnd
LND_SOURCE=path/to/lnd
NETWORK=mainnet
MACAROON_PATH="$LND_DIR/data/chain/bitcoin/$NETWORK/admin.macaroon"
TLS_PATH="$LND_DIR/tls.cert"

grpcurl \
    -import-path $LND_SOURCE/lnrpc/ \
    -proto switchrpc/switch.proto \
    -cacert $TLS_PATH \
    -H "macaroon: $(xxd -ps -u -c 1000 $MACAROON_PATH)" \
    -d '{ "attempt_ids": <uint64> }' \
    $GRPC_HOST \
    switchrpc.Switch/DeleteAttempts

REST

Javascript

const fs = require('fs');
const request = require('request');

const REST_HOST = 'localhost:8080'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'

let requestBody = {
  attempt_ids: <array>, // <uint64> 
};
let options = {
  url: `https://${REST_HOST}/v2/switch/deleteattempts`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "results": <array>, // <AttemptDeletionResult> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8080'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

url = f'https://{REST_HOST}/v2/switch/deleteattempts'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'attempt_ids': <uint64>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "results": <AttemptDeletionResult>,
# }

curl

REST_HOST=localhost:8080
LND_DIR=~/.lnd
NETWORK=mainnet
MACAROON_PATH="$LND_DIR/data/chain/bitcoin/$NETWORK/admin.macaroon"
TLS_PATH="$LND_DIR/tls.cert"

curl -X POST \
    --cacert $TLS_PATH \
    -H "Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $MACAROON_PATH)" \
    -d '{ "attempt_ids": <uint64> }' \
    https://$REST_HOST/v2/switch/deleteattempts

Messages

switchrpc.DeleteAttemptsRequest

Source: switchrpc/switch.proto

Field	gRPC Type	REST Type	REST Placement
attempt_ids The attempt IDs to delete from the server's attempt store. Only terminal (settled or failed) attempts will be deleted. Pending (in-flight) attempts are skipped and reported with a DELETION_PENDING status.	uint64[]	array	body

switchrpc.DeleteAttemptsResponse

Source: switchrpc/switch.proto

Field	gRPC Type	REST Type
results Per-attempt deletion outcomes. The order corresponds to the order of attempt_ids in the request.	AttemptDeletionResult[]	array

Nested Messages

switchrpc.AttemptDeletionResult

Field	gRPC Type	REST Type
attempt_id The attempt ID this result corresponds to.	uint64	string
status The outcome of the deletion for this attempt.	AttemptDeletionStatus	string

Enums

switchrpc.AttemptDeletionStatus

Name	Number
DELETION_OK The attempt result was successfully deleted from the store.	0
DELETION_PENDING The attempt is still in-flight (pending) and cannot be safely deleted.	1
DELETION_NOT_FOUND The attempt ID was not found in the store. This may indicate a client bug (wrong ID, wrong backend) since the server has no record of this attempt ever existing.	2
DELETION_FAILED The attempt record exists but could not be processed (e.g. deserialization error). The record remains in the store.	3