diff --git a/lib/api/tapd.ts b/lib/api/tapd.ts index 62285a8..3899a6d 100644 --- a/lib/api/tapd.ts +++ b/lib/api/tapd.ts @@ -1,6 +1,10 @@ import { serviceNames as sn } from '../types/proto/schema'; import { AssetWallet } from '../types/proto/tapd/assetwalletrpc/assetwallet'; import { Mint } from '../types/proto/tapd/mintrpc/mint'; +import { PriceOracle } from '../types/proto/tapd/priceoraclerpc/price_oracle'; +import { Rfq } from '../types/proto/tapd/rfqrpc/rfq'; +import { TaprootAssetChannels } from '../types/proto/tapd/tapchannelrpc/tapchannel'; +import { TapDev } from '../types/proto/tapd/tapdevrpc/tapdev'; import { TaprootAssets } from '../types/proto/tapd/taprootassets'; import { Universe } from '../types/proto/tapd/universerpc/universe'; @@ -11,12 +15,23 @@ class TaprootAssetsApi { taprootAssets: TaprootAssets; assetWallet: AssetWallet; mint: Mint; + priceOracle: PriceOracle; + rfq: Rfq; + tapChannels: TaprootAssetChannels; + tapDev: TapDev; universe: Universe; constructor(createRpc: Function, lnc: any) { this.taprootAssets = createRpc(sn.taprpc.TaprootAssets, lnc); - this.mint = createRpc(sn.mintrpc.Mint, lnc); this.assetWallet = createRpc(sn.assetwalletrpc.AssetWallet, lnc); + this.mint = createRpc(sn.mintrpc.Mint, lnc); + this.priceOracle = createRpc(sn.priceoraclerpc.PriceOracle, lnc); + this.rfq = createRpc(sn.rfqrpc.Rfq, lnc); + this.tapChannels = createRpc( + sn.tapchannelrpc.TaprootAssetChannels, + lnc + ); + this.tapDev = createRpc(sn.tapdevrpc.TapDev, lnc); this.universe = createRpc(sn.universerpc.Universe, lnc); } } diff --git a/lib/types/proto/index.ts b/lib/types/proto/index.ts index 082e6af..5a5463c 100644 --- a/lib/types/proto/index.ts +++ b/lib/types/proto/index.ts @@ -13,6 +13,10 @@ import * as looprpc from './looprpc'; import * as poolrpc from './poolrpc'; import * as assetwalletrpc from './assetwalletrpc'; import * as mintrpc from './mintrpc'; +import * as priceoraclerpc from './priceoraclerpc'; +import * as rfqrpc from './rfqrpc'; +import * as tapchannelrpc from './tapchannelrpc'; +import * as tapdevrpc from './tapdevrpc'; import * as taprpc from './taprpc'; import * as universerpc from './universerpc'; export { @@ -31,6 +35,10 @@ export { poolrpc, assetwalletrpc, mintrpc, + priceoraclerpc, + rfqrpc, + tapchannelrpc, + tapdevrpc, taprpc, universerpc }; diff --git a/lib/types/proto/lnd/invoicesrpc/invoices.ts b/lib/types/proto/lnd/invoicesrpc/invoices.ts index f326b4f..61d2fa2 100644 --- a/lib/types/proto/lnd/invoicesrpc/invoices.ts +++ b/lib/types/proto/lnd/invoicesrpc/invoices.ts @@ -121,6 +121,57 @@ export interface LookupInvoiceMsg { lookupModifier: LookupModifier; } +/** CircuitKey is a unique identifier for an HTLC. */ +export interface CircuitKey { + /** The id of the channel that the is part of this circuit. */ + chanId: string; + /** The index of the incoming htlc in the incoming channel. */ + htlcId: string; +} + +export interface HtlcModifyRequest { + /** + * The invoice the intercepted HTLC is attempting to settle. The HTLCs in + * the invoice are only HTLCs that have already been accepted or settled, + * not including the current intercepted HTLC. + */ + invoice: Invoice | undefined; + /** The unique identifier of the HTLC of this intercepted HTLC. */ + exitHtlcCircuitKey: CircuitKey | undefined; + /** The amount in milli-satoshi that the exit HTLC is attempting to pay. */ + exitHtlcAmt: string; + /** The absolute expiry height of the exit HTLC. */ + exitHtlcExpiry: number; + /** The current block height. */ + currentHeight: number; + /** The wire message custom records of the exit HTLC. */ + exitHtlcWireCustomRecords: { [key: string]: Uint8Array | string }; +} + +export interface HtlcModifyRequest_ExitHtlcWireCustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + +export interface HtlcModifyResponse { + /** The circuit key of the HTLC that the client wants to modify. */ + circuitKey: CircuitKey | undefined; + /** + * The modified amount in milli-satoshi that the exit HTLC is paying. This + * value can be different from the actual on-chain HTLC amount, in case the + * HTLC carries other valuable items, as can be the case with custom channel + * types. + */ + amtPaid?: string | undefined; + /** + * This flag indicates whether the HTLCs associated with the invoices should + * be cancelled. The interceptor client may set this field if some + * unexpected behavior is encountered. Setting this will ignore the amt_paid + * field. + */ + cancelSet: boolean; +} + /** * Invoices is a service that can be used to create, accept, settle and cancel * invoices. @@ -162,10 +213,21 @@ export interface Invoices { request?: DeepPartial ): Promise; /** - * LookupInvoiceV2 attempts to look up at invoice. An invoice can be refrenced + * LookupInvoiceV2 attempts to look up at invoice. An invoice can be referenced * using either its payment hash, payment address, or set ID. */ lookupInvoiceV2(request?: DeepPartial): Promise; + /** + * HtlcModifier is a bidirectional streaming RPC that allows a client to + * intercept and modify the HTLCs that attempt to settle the given invoice. The + * server will send HTLCs of invoices to the client and the client can modify + * some aspects of the HTLC in order to pass the invoice acceptance tests. + */ + htlcModifier( + request?: DeepPartial, + onMessage?: (msg: HtlcModifyRequest) => void, + onError?: (err: Error) => void + ): void; } type Builtin = diff --git a/lib/types/proto/lnd/lightning.ts b/lib/types/proto/lnd/lightning.ts index 9867fd2..de8a03c 100644 --- a/lib/types/proto/lnd/lightning.ts +++ b/lib/types/proto/lnd/lightning.ts @@ -73,8 +73,17 @@ export enum CommitmentType { * channel before its maturity date. */ SCRIPT_ENFORCED_LEASE = 'SCRIPT_ENFORCED_LEASE', - /** SIMPLE_TAPROOT - TODO(roasbeef): need script enforce mirror type for the above as well? */ + /** + * SIMPLE_TAPROOT - A channel that uses musig2 for the funding output, and the new tapscript + * features where relevant. + */ SIMPLE_TAPROOT = 'SIMPLE_TAPROOT', + /** + * SIMPLE_TAPROOT_OVERLAY - Identical to the SIMPLE_TAPROOT channel type, but with extra functionality. + * This channel type also commits to additional meta data in the tapscript + * leaves for the scripts in a channel. + */ + SIMPLE_TAPROOT_OVERLAY = 'SIMPLE_TAPROOT_OVERLAY', UNRECOGNIZED = 'UNRECOGNIZED' } @@ -164,6 +173,8 @@ export enum PaymentFailureReason { FAILURE_REASON_INCORRECT_PAYMENT_DETAILS = 'FAILURE_REASON_INCORRECT_PAYMENT_DETAILS', /** FAILURE_REASON_INSUFFICIENT_BALANCE - Insufficient local balance. */ FAILURE_REASON_INSUFFICIENT_BALANCE = 'FAILURE_REASON_INSUFFICIENT_BALANCE', + /** FAILURE_REASON_CANCELED - The payment was canceled. */ + FAILURE_REASON_CANCELED = 'FAILURE_REASON_CANCELED', UNRECOGNIZED = 'UNRECOGNIZED' } @@ -729,9 +740,8 @@ export interface SendCoinsRequest { */ satPerByte: string; /** - * If set, then the amount field will be ignored, and lnd will attempt to - * send all the coins under control of the internal wallet to the specified - * address. + * If set, the amount field should be unset. It indicates lnd will send all + * wallet coins or all selected coins to the specified address. */ sendAll: boolean; /** An optional label for the transaction, limited to 500 characters. */ @@ -745,6 +755,8 @@ export interface SendCoinsRequest { spendUnconfirmed: boolean; /** The strategy to use for selecting coins. */ coinSelectionStrategy: CoinSelectionStrategy; + /** A list of selected outpoints as inputs for the transaction. */ + outpoints: OutPoint[]; } export interface SendCoinsResponse { @@ -1027,6 +1039,8 @@ export interface Channel { * the channel's operation. */ memo: string; + /** Custom channel data that might be populated in custom channels. */ + customChannelData: Uint8Array | string; } export interface ListChannelsRequest { @@ -1356,9 +1370,39 @@ export interface ChannelOpenUpdate { channelPoint: ChannelPoint | undefined; } +export interface CloseOutput { + /** + * The amount in satoshi of this close output. This amount is the final + * commitment balance of the channel and the actual amount paid out on chain + * might be smaller due to subtracted fees. + */ + amountSat: string; + /** The pkScript of the close output. */ + pkScript: Uint8Array | string; + /** Whether this output is for the local or remote node. */ + isLocal: boolean; + /** + * The TLV encoded custom channel data records for this output, which might + * be set for custom channels. + */ + customChannelData: Uint8Array | string; +} + export interface ChannelCloseUpdate { closingTxid: Uint8Array | string; success: boolean; + /** + * The local channel close output. If the local channel balance was dust to + * begin with, this output will not be set. + */ + localCloseOutput: CloseOutput | undefined; + /** + * The remote channel close output. If the remote channel balance was dust + * to begin with, this output will not be set. + */ + remoteCloseOutput: CloseOutput | undefined; + /** Any additional outputs that might be added for custom channel types. */ + additionalOutputs: CloseOutput[]; } export interface CloseChannelRequest { @@ -1991,6 +2035,8 @@ export interface PendingChannelsResponse_PendingChannel { * impacts the channel's operation. */ memo: string; + /** Custom channel data that might be populated in custom channels. */ + customChannelData: Uint8Array | string; } export interface PendingChannelsResponse_PendingOpenChannel { @@ -2212,6 +2258,11 @@ export interface ChannelBalanceResponse { pendingOpenLocalBalance: Amount | undefined; /** Sum of channels pending remote balances. */ pendingOpenRemoteBalance: Amount | undefined; + /** + * Custom channel data that might be populated if there are custom channels + * present. + */ + customChannelData: Uint8Array | string; } export interface QueryRoutesRequest { @@ -2507,6 +2558,16 @@ export interface Route { totalFeesMsat: string; /** The total amount in millisatoshis. */ totalAmtMsat: string; + /** + * The actual on-chain amount that was sent out to the first hop. This value is + * only different from the total_amt_msat field if this is a custom channel + * payment and the value transported in the HTLC is different from the BTC + * amount in the HTLC. If this value is zero, then this is an old payment that + * didn't have this value yet and can be ignored. + */ + firstHopAmountMsat: string; + /** Custom channel data that might be populated in custom channels. */ + customChannelData: Uint8Array | string; } export interface NodeInfoRequest { @@ -2666,6 +2727,11 @@ export interface ChanInfoRequest { * output index for the channel. */ chanId: string; + /** + * The channel point of the channel in format funding_txid:output_index. If + * chan_id is specified, this field is ignored. + */ + chanPoint: string; } export interface NetworkInfoRequest {} @@ -3006,6 +3072,17 @@ export interface Invoice { * Note: Output only, don't specify for creating an invoice. */ ampInvoiceState: { [key: string]: AMPInvoiceState }; + /** + * Signals that the invoice should include blinded paths to hide the true + * identity of the recipient. + */ + isBlinded: boolean; + /** + * Config values to use when creating blinded paths for this invoice. These + * can be used to override the defaults config values provided in by the + * global config. This field is only used if is_blinded is true. + */ + blindedPathConfig: BlindedPathConfig | undefined; } export enum Invoice_InvoiceState { @@ -3026,6 +3103,30 @@ export interface Invoice_AmpInvoiceStateEntry { value: AMPInvoiceState | undefined; } +export interface BlindedPathConfig { + /** + * The minimum number of real hops to include in a blinded path. This doesn't + * include our node, so if the minimum is 1, then the path will contain at + * minimum our node along with an introduction node hop. If it is zero then + * the shortest path will use our node as an introduction node. + */ + minNumRealHops?: number | undefined; + /** + * The number of hops to include in a blinded path. This doesn't include our + * node, so if it is 1, then the path will contain our node along with an + * introduction node or dummy node hop. If paths shorter than NumHops is + * found, then they will be padded using dummy hops. + */ + numHops?: number | undefined; + /** The maximum number of blinded paths to select and add to an invoice. */ + maxNumPaths?: number | undefined; + /** + * A list of node IDs of nodes that should not be used in any of our generated + * blinded paths. + */ + nodeOmissionList: Uint8Array | string[]; +} + /** Details of an HTLC that paid to an invoice */ export interface InvoiceHTLC { /** Short channel id over which the htlc was received. */ @@ -3050,6 +3151,8 @@ export interface InvoiceHTLC { mppTotalAmtMsat: string; /** Details relevant to AMP HTLCs, only populated if this is an AMP HTLC. */ amp: AMP | undefined; + /** Custom channel data that might be populated in custom channels. */ + customChannelData: Uint8Array | string; } export interface InvoiceHTLC_CustomRecordsEntry { @@ -3232,6 +3335,11 @@ export interface Payment { */ paymentIndex: string; failureReason: PaymentFailureReason; + /** + * The custom TLV records that were sent to the first hop as part of the HTLC + * wire message for this payment. + */ + firstHopCustomRecords: { [key: string]: Uint8Array | string }; } export enum Payment_PaymentStatus { @@ -3252,6 +3360,11 @@ export enum Payment_PaymentStatus { UNRECOGNIZED = 'UNRECOGNIZED' } +export interface Payment_FirstHopCustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + export interface HTLCAttempt { /** The unique ID that is used for this attempt. */ attemptId: string; @@ -3408,6 +3521,7 @@ export interface PayReq { paymentAddr: Uint8Array | string; numMsat: string; features: { [key: number]: Feature }; + blindedPaths: BlindedPaymentPath[]; } export interface PayReq_FeaturesEntry { diff --git a/lib/types/proto/lnd/routerrpc/router.ts b/lib/types/proto/lnd/routerrpc/router.ts index dd5904e..9a1be56 100644 --- a/lib/types/proto/lnd/routerrpc/router.ts +++ b/lib/types/proto/lnd/routerrpc/router.ts @@ -8,6 +8,7 @@ import type { Failure, HTLCAttempt, ChannelPoint, + AliasMap, Payment } from '../lightning'; @@ -63,9 +64,20 @@ export enum PaymentState { } export enum ResolveHoldForwardAction { + /** + * SETTLE - SETTLE is an action that is used to settle an HTLC instead of forwarding + * it. + */ SETTLE = 'SETTLE', + /** FAIL - FAIL is an action that is used to fail an HTLC backwards. */ FAIL = 'FAIL', + /** RESUME - RESUME is an action that is used to resume a forward HTLC. */ RESUME = 'RESUME', + /** + * RESUME_MODIFIED - RESUME_MODIFIED is an action that is used to resume a hold forward HTLC + * with modifications specified during interception. + */ + RESUME_MODIFIED = 'RESUME_MODIFIED', UNRECOGNIZED = 'UNRECOGNIZED' } @@ -202,6 +214,22 @@ export interface SendPaymentRequest { * only, to 1 to optimize for reliability only or a value inbetween for a mix. */ timePref: number; + /** + * If set, the payment loop can be interrupted by manually canceling the + * payment context, even before the payment timeout is reached. Note that the + * payment may still succeed after cancellation, as in-flight attempts can + * still settle afterwards. Canceling will only prevent further attempts from + * being sent. + */ + cancelable: boolean; + /** + * An optional field that can be used to pass an arbitrary set of TLV records + * to the first hop peer of this payment. This can be used to pass application + * specific data during the payment attempt. Record types are required to be in + * the custom range >= 65536. When using REST, the values must be encoded as + * base64. + */ + firstHopCustomRecords: { [key: string]: Uint8Array | string }; } export interface SendPaymentRequest_DestCustomRecordsEntry { @@ -209,6 +237,11 @@ export interface SendPaymentRequest_DestCustomRecordsEntry { value: Uint8Array | string; } +export interface SendPaymentRequest_FirstHopCustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + export interface TrackPaymentRequest { /** The hash of the payment to look up. */ paymentHash: Uint8Array | string; @@ -292,6 +325,19 @@ export interface SendToRouteRequest { * routes, incorrect payment details, or insufficient funds. */ skipTempErr: boolean; + /** + * An optional field that can be used to pass an arbitrary set of TLV records + * to the first hop peer of this payment. This can be used to pass application + * specific data during the payment attempt. Record types are required to be in + * the custom range >= 65536. When using REST, the values must be encoded as + * base64. + */ + firstHopCustomRecords: { [key: string]: Uint8Array | string }; +} + +export interface SendToRouteRequest_FirstHopCustomRecordsEntry { + key: string; + value: Uint8Array | string; } export interface SendToRouteResponse { @@ -528,6 +574,19 @@ export interface BuildRouteRequest { * This is also called payment secret in specifications (e.g. BOLT 11). */ paymentAddr: Uint8Array | string; + /** + * An optional field that can be used to pass an arbitrary set of TLV records + * to the first hop peer of this payment. This can be used to pass application + * specific data during the payment attempt. Record types are required to be in + * the custom range >= 65536. When using REST, the values must be encoded as + * base64. + */ + firstHopCustomRecords: { [key: string]: Uint8Array | string }; +} + +export interface BuildRouteRequest_FirstHopCustomRecordsEntry { + key: string; + value: Uint8Array | string; } export interface BuildRouteResponse { @@ -685,6 +744,8 @@ export interface ForwardHtlcInterceptRequest { * channel from force-closing. */ autoFailHeight: number; + /** The custom records of the peer's incoming p2p wire message. */ + inWireCustomRecords: { [key: string]: Uint8Array | string }; } export interface ForwardHtlcInterceptRequest_CustomRecordsEntry { @@ -692,10 +753,17 @@ export interface ForwardHtlcInterceptRequest_CustomRecordsEntry { value: Uint8Array | string; } +export interface ForwardHtlcInterceptRequest_InWireCustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + /** * ForwardHtlcInterceptResponse enables the caller to resolve a previously hold * forward. The caller can choose either to: * - `Resume`: Execute the default behavior (usually forward). + * - `ResumeModified`: Execute the default behavior (usually forward) with HTLC + * field modifications. * - `Reject`: Fail the htlc backwards. * - `Settle`: Settle this htlc with a given preimage. */ @@ -726,6 +794,28 @@ export interface ForwardHtlcInterceptResponse { * default value for this field. */ failureCode: Failure_FailureCode; + /** + * The amount that was set on the p2p wire message of the incoming HTLC. + * This field is ignored if the action is not RESUME_MODIFIED or the amount + * is zero. + */ + inAmountMsat: string; + /** + * The amount to set on the p2p wire message of the resumed HTLC. This field + * is ignored if the action is not RESUME_MODIFIED or the amount is zero. + */ + outAmountMsat: string; + /** + * Any custom records that should be set on the p2p wire message message of + * the resumed HTLC. This field is ignored if the action is not + * RESUME_MODIFIED. + */ + outWireCustomRecords: { [key: string]: Uint8Array | string }; +} + +export interface ForwardHtlcInterceptResponse_OutWireCustomRecordsEntry { + key: string; + value: Uint8Array | string; } export interface UpdateChanStatusRequest { @@ -735,6 +825,22 @@ export interface UpdateChanStatusRequest { export interface UpdateChanStatusResponse {} +export interface AddAliasesRequest { + aliasMaps: AliasMap[]; +} + +export interface AddAliasesResponse { + aliasMaps: AliasMap[]; +} + +export interface DeleteAliasesRequest { + aliasMaps: AliasMap[]; +} + +export interface DeleteAliasesResponse { + aliasMaps: AliasMap[]; +} + /** * Router is a service that offers advanced interaction with the router * subsystem of the daemon. @@ -922,6 +1028,26 @@ export interface Router { updateChanStatus( request?: DeepPartial ): Promise; + /** + * XAddLocalChanAliases is an experimental API that creates a set of new + * channel SCID alias mappings. The final total set of aliases in the manager + * after the add operation is returned. This is only a locally stored alias, + * and will not be communicated to the channel peer via any message. Therefore, + * routing over such an alias will only work if the peer also calls this same + * RPC on their end. If an alias already exists, an error is returned + */ + xAddLocalChanAliases( + request?: DeepPartial + ): Promise; + /** + * XDeleteLocalChanAliases is an experimental API that deletes a set of alias + * mappings. The final total set of aliases in the manager after the delete + * operation is returned. The deletion will not be communicated to the channel + * peer via any message. + */ + xDeleteLocalChanAliases( + request?: DeepPartial + ): Promise; } type Builtin = diff --git a/lib/types/proto/lnd/walletrpc/walletkit.ts b/lib/types/proto/lnd/walletrpc/walletkit.ts index 007d7d4..f232f2f 100644 --- a/lib/types/proto/lnd/walletrpc/walletkit.ts +++ b/lib/types/proto/lnd/walletrpc/walletkit.ts @@ -682,6 +682,8 @@ export interface EstimateFeeResponse { * confirmation target in the request. */ satPerKw: string; + /** The current minimum relay fee based on our chain backend in sat/kw. */ + minRelayFeeSatPerKw: string; } export interface PendingSweep { diff --git a/lib/types/proto/priceoraclerpc.ts b/lib/types/proto/priceoraclerpc.ts new file mode 100644 index 0000000..d9680b9 --- /dev/null +++ b/lib/types/proto/priceoraclerpc.ts @@ -0,0 +1 @@ +export * from './tapd/priceoraclerpc/price_oracle'; diff --git a/lib/types/proto/rfqrpc.ts b/lib/types/proto/rfqrpc.ts new file mode 100644 index 0000000..a341fcc --- /dev/null +++ b/lib/types/proto/rfqrpc.ts @@ -0,0 +1 @@ +export * from './tapd/rfqrpc/rfq'; diff --git a/lib/types/proto/schema.ts b/lib/types/proto/schema.ts index d32d01e..63be91f 100644 --- a/lib/types/proto/schema.ts +++ b/lib/types/proto/schema.ts @@ -31,6 +31,12 @@ export const serviceNames = { }, assetwalletrpc: { AssetWallet: 'assetwalletrpc.AssetWallet' }, mintrpc: { Mint: 'mintrpc.Mint' }, + priceoraclerpc: { PriceOracle: 'priceoraclerpc.PriceOracle' }, + rfqrpc: { Rfq: 'rfqrpc.Rfq' }, + tapchannelrpc: { + TaprootAssetChannels: 'tapchannelrpc.TaprootAssetChannels' + }, + tapdevrpc: { TapDev: 'tapdevrpc.TapDev' }, taprpc: { TaprootAssets: 'taprpc.TaprootAssets' }, universerpc: { Universe: 'universerpc.Universe' } }; @@ -46,6 +52,7 @@ export const subscriptionMethods = [ 'chainrpc.ChainNotifier.RegisterSpendNtfn', 'chainrpc.ChainNotifier.RegisterBlockEpochNtfn', 'invoicesrpc.Invoices.SubscribeSingleInvoice', + 'invoicesrpc.Invoices.HtlcModifier', 'lnrpc.Lightning.SubscribeTransactions', 'lnrpc.Lightning.SubscribePeerEvents', 'lnrpc.Lightning.SubscribeChannelEvents', @@ -70,6 +77,31 @@ export const subscriptionMethods = [ 'poolrpc.ChannelAuctioneer.SubscribeBatchAuction', 'poolrpc.ChannelAuctioneer.SubscribeSidecar', 'poolrpc.HashMail.RecvStream', - 'taprpc.TaprootAssets.SubscribeSendAssetEventNtfns', - 'taprpc.TaprootAssets.SubscribeReceiveAssetEventNtfns' + 'lnrpc.Lightning.SubscribeTransactions', + 'lnrpc.Lightning.SubscribePeerEvents', + 'lnrpc.Lightning.SubscribeChannelEvents', + 'lnrpc.Lightning.OpenChannel', + 'lnrpc.Lightning.ChannelAcceptor', + 'lnrpc.Lightning.CloseChannel', + 'lnrpc.Lightning.SendPayment', + 'lnrpc.Lightning.SendToRoute', + 'lnrpc.Lightning.SubscribeInvoices', + 'lnrpc.Lightning.SubscribeChannelGraph', + 'lnrpc.Lightning.SubscribeChannelBackups', + 'lnrpc.Lightning.RegisterRPCMiddleware', + 'lnrpc.Lightning.SubscribeCustomMessages', + 'mintrpc.Mint.SubscribeMintEvents', + 'rfqrpc.Rfq.SubscribeRfqEventNtfns', + 'routerrpc.Router.SendPaymentV2', + 'routerrpc.Router.TrackPaymentV2', + 'routerrpc.Router.TrackPayments', + 'routerrpc.Router.SubscribeHtlcEvents', + 'routerrpc.Router.SendPayment', + 'routerrpc.Router.TrackPayment', + 'routerrpc.Router.HtlcInterceptor', + 'tapchannelrpc.TaprootAssetChannels.SendPayment', + 'tapdevrpc.TapDev.SubscribeSendAssetEventNtfns', + 'tapdevrpc.TapDev.SubscribeReceiveAssetEventNtfns', + 'taprpc.TaprootAssets.SubscribeReceiveEvents', + 'taprpc.TaprootAssets.SubscribeSendEvents' ]; diff --git a/lib/types/proto/tapchannelrpc.ts b/lib/types/proto/tapchannelrpc.ts new file mode 100644 index 0000000..b945858 --- /dev/null +++ b/lib/types/proto/tapchannelrpc.ts @@ -0,0 +1 @@ +export * from './tapd/tapchannelrpc/tapchannel'; diff --git a/lib/types/proto/tapd/assetwalletrpc/assetwallet.ts b/lib/types/proto/tapd/assetwalletrpc/assetwallet.ts index 4cef8d0..57a9671 100644 --- a/lib/types/proto/tapd/assetwalletrpc/assetwallet.ts +++ b/lib/types/proto/tapd/assetwalletrpc/assetwallet.ts @@ -6,24 +6,55 @@ import type { SendAssetResponse } from '../taprootassets'; -export interface FundVirtualPsbtRequest { +export enum CoinSelectType { /** - * Use an existing PSBT packet as the template for the funded PSBT. - * - * TODO(guggero): Actually implement this. We can't use the "reserved" - * keyword here because we're in a oneof, so we add the field but implement - * it later. + * COIN_SELECT_DEFAULT - Use the default coin selection type, which currently allows script keys and + * key spend paths. + */ + COIN_SELECT_DEFAULT = 'COIN_SELECT_DEFAULT', + /** + * COIN_SELECT_BIP86_ONLY - Explicitly only select inputs that are known to be BIP-086 compliant (have + * a key-spend path only and no script tree). + */ + COIN_SELECT_BIP86_ONLY = 'COIN_SELECT_BIP86_ONLY', + /** + * COIN_SELECT_SCRIPT_TREES_ALLOWED - Allow the selection of inputs that have a script tree spend path as well as + * a key spend path. */ + COIN_SELECT_SCRIPT_TREES_ALLOWED = 'COIN_SELECT_SCRIPT_TREES_ALLOWED', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export interface FundVirtualPsbtRequest { + /** Use an existing PSBT packet as the template for the funded PSBT. */ psbt: Uint8Array | string | undefined; /** Use the asset outputs and optional asset inputs from this raw template. */ raw: TxTemplate | undefined; + /** + * Specify the type of coins that should be selected. Defaults to allowing both + * script trees and BIP-086 compliant inputs. + */ + coinSelectType: CoinSelectType; } export interface FundVirtualPsbtResponse { - /** The funded but not yet signed PSBT packet. */ + /** The funded but not yet signed virtual PSBT packet. */ fundedPsbt: Uint8Array | string; /** The index of the added change output or -1 if no change was left over. */ changeOutputIndex: number; + /** + * The list of passive virtual transactions that are anchored in the same BTC + * level anchor transaction inputs as the funded "active" asset above. These + * assets can be ignored when using the AnchorVirtualPsbts RPC, since they are + * retrieved, signed and committed automatically in that method. But the + * passive assets have to be included in the CommitVirtualPsbts RPC which is + * used when custom BTC level anchor transactions are created. + * The main difference to the "active" asset above is that the passive assets + * will not get their own entry in the transfer table of the database, since + * they are just carried along and not directly affected by the direct user + * action. + */ + passiveAssetPsbts: Uint8Array | string[]; } export interface TxTemplate { @@ -84,6 +115,116 @@ export interface AnchorVirtualPsbtsRequest { virtualPsbts: Uint8Array | string[]; } +export interface CommitVirtualPsbtsRequest { + /** + * The list of virtual transactions that should be mapped to the given BTC + * level anchor transaction template. The virtual transactions are expected to + * be signed (or use ASSET_VERSION_V1 with segregated witness to allow for + * signing after committing) and ready to be committed to the anchor + * transaction. + */ + virtualPsbts: Uint8Array | string[]; + /** + * The list of passive virtual transactions that are anchored in the same BTC + * level anchor transaction inputs as the "active" assets above. These can be + * obtained by calling FundVirtualPsbt and using the passive assets returned. + * The virtual transactions are expected to be signed (or use ASSET_VERSION_V1 + * with segregated witness to allow for signing after committing) and ready to + * be committed to the anchor transaction. + * The main difference to the "active" assets above is that the passive assets + * will not get their own entry in the transfer table of the database, since + * they are just carried along and not directly affected by the direct user + * action. + */ + passiveAssetPsbts: Uint8Array | string[]; + /** + * The template of the BTC level anchor transaction that the virtual + * transactions should be mapped to. The template is expected to already + * contain all asset related inputs and outputs corresponding to the virtual + * transactions given above. This can be achieved by using + * tapfreighter.PrepareAnchoringTemplate for example. + */ + anchorPsbt: Uint8Array | string; + /** + * Use the existing output within the anchor PSBT with the specified + * index as the change output. Any leftover change will be added to the + * already specified amount of that output. To add a new change output to + * the PSBT, set the "add" field below instead. + */ + existingOutputIndex: number | undefined; + /** Add a new P2TR change output to the PSBT if required. */ + add: boolean | undefined; + /** The target number of blocks that the transaction should be confirmed in. */ + targetConf: number | undefined; + /** + * The fee rate, expressed in sat/vbyte, that should be used to fund the + * BTC level anchor transaction. + */ + satPerVbyte: string | undefined; +} + +export interface CommitVirtualPsbtsResponse { + /** + * The funded BTC level anchor transaction with all outputs updated to commit + * to the virtual transactions given. The transaction is ready to be signed, + * unless some of the asset inputs don't belong to this daemon, in which case + * the anchor input derivation info must be added to those inputs first. + */ + anchorPsbt: Uint8Array | string; + /** + * The updated virtual transactions that now contain the state transition + * proofs for being committed to the BTC level anchor transaction above. If the + * assets in the virtual transaction outputs are ASSET_VERSION_V1 and not yet + * signed, then the proofs need to be updated to include the witness before + * they become fully valid. + */ + virtualPsbts: Uint8Array | string[]; + /** + * The updated passive virtual transactions that were committed to the same BTC + * level anchor transaction as the "active" virtual transactions given. If the + * assets in the virtual transaction outputs are ASSET_VERSION_V1 and not yet + * signed, then the proofs need to be updated to include the witness before + * they become fully valid. + */ + passiveAssetPsbts: Uint8Array | string[]; + /** The index of the (added) change output or -1 if no change was left over. */ + changeOutputIndex: number; + /** + * The list of UTXO lock leases that were acquired for the inputs in the funded + * PSBT packet from lnd. Only inputs added to the PSBT by this RPC are locked, + * inputs that were already present in the PSBT are not locked. + */ + lndLockedUtxos: OutPoint[]; +} + +export interface PublishAndLogRequest { + /** + * The funded BTC level anchor transaction with all outputs updated to commit + * to the virtual transactions given. The transaction is ready to be signed, + * unless some of the asset inputs don't belong to this daemon, in which case + * the anchor input derivation info must be added to those inputs first. + */ + anchorPsbt: Uint8Array | string; + /** + * The updated virtual transactions that contain the state transition proofs + * of being committed to the BTC level anchor transaction above. + */ + virtualPsbts: Uint8Array | string[]; + /** + * The updated passive virtual transactions that contain the state transition + * proofs of being committed to the BTC level anchor transaction above. + */ + passiveAssetPsbts: Uint8Array | string[]; + /** The index of the (added) change output or -1 if no change was left over. */ + changeOutputIndex: number; + /** + * The list of UTXO lock leases that were acquired for the inputs in the funded + * PSBT packet from lnd. Only inputs added to the PSBT by this RPC are locked, + * inputs that were already present in the PSBT are not locked. + */ + lndLockedUtxos: OutPoint[]; +} + export interface NextInternalKeyRequest { keyFamily: number; } @@ -100,10 +241,41 @@ export interface NextScriptKeyResponse { scriptKey: ScriptKey | undefined; } +export interface QueryInternalKeyRequest { + /** + * The internal key to look for. This can either be the 32-byte x-only raw + * internal key or the 33-byte raw internal key with the parity byte. + */ + internalKey: Uint8Array | string; +} + +export interface QueryInternalKeyResponse { + internalKey: KeyDescriptor | undefined; +} + +export interface QueryScriptKeyRequest { + /** + * The tweaked script key to look for. This can either be the 32-byte + * x-only tweaked script key or the 33-byte tweaked script key with the + * parity byte. + */ + tweakedScriptKey: Uint8Array | string; +} + +export interface QueryScriptKeyResponse { + scriptKey: ScriptKey | undefined; +} + export interface ProveAssetOwnershipRequest { assetId: Uint8Array | string; scriptKey: Uint8Array | string; outpoint: OutPoint | undefined; + /** + * An optional 32-byte challenge that may be used to bind the generated + * proof. This challenge needs to be also presented on the + * VerifyAssetOwnership RPC in order to check the proof against it. + */ + challenge: Uint8Array | string; } export interface ProveAssetOwnershipResponse { @@ -112,10 +284,26 @@ export interface ProveAssetOwnershipResponse { export interface VerifyAssetOwnershipRequest { proofWithWitness: Uint8Array | string; + /** + * An optional 32-byte challenge that may be used to check the ownership + * proof against. This challenge must match the one that the prover used + * on the ProveAssetOwnership RPC. + */ + challenge: Uint8Array | string; } export interface VerifyAssetOwnershipResponse { validProof: boolean; + /** The outpoint the proof commits to. */ + outpoint: OutPoint | undefined; + /** The outpoint in the human-readable form "hash:index". */ + outpointStr: string; + /** The block hash the output is part of. */ + blockHash: Uint8Array | string; + /** The block hash as hexadecimal string of the byte-reversed hash. */ + blockHashStr: string; + /** The block height of the block the output is part of. */ + blockHeight: number; } export interface RemoveUTXOLeaseRequest { @@ -125,6 +313,14 @@ export interface RemoveUTXOLeaseRequest { export interface RemoveUTXOLeaseResponse {} +export interface DeclareScriptKeyRequest { + scriptKey: ScriptKey | undefined; +} + +export interface DeclareScriptKeyResponse { + scriptKey: ScriptKey | undefined; +} + export interface AssetWallet { /** * FundVirtualPsbt selects inputs from the available asset commitments to fund @@ -142,14 +338,34 @@ export interface AssetWallet { ): Promise; /** * AnchorVirtualPsbts merges and then commits multiple virtual transactions in - * a single BTC level anchor transaction. - * - * TODO(guggero): Actually implement accepting and merging multiple - * transactions. + * a single BTC level anchor transaction. This RPC should be used if the BTC + * level anchor transaction of the assets to be spent are encumbered by a + * normal key and don't require any special spending conditions. For any custom + * spending conditions on the BTC level, the two RPCs CommitVirtualPsbts and + * PublishAndLogTransfer should be used instead (which in combination do the + * same as this RPC but allow for more flexibility). */ anchorVirtualPsbts( request?: DeepPartial ): Promise; + /** + * CommitVirtualPsbts creates the output commitments and proofs for the given + * virtual transactions by committing them to the BTC level anchor transaction. + * In addition, the BTC level anchor transaction is funded and prepared up to + * the point where it is ready to be signed. + */ + commitVirtualPsbts( + request?: DeepPartial + ): Promise; + /** + * PublishAndLogTransfer accepts a fully committed and signed anchor + * transaction and publishes it to the Bitcoin network. It also logs the + * transfer of the given active and passive assets in the database and ships + * any outgoing proofs to the counterparties. + */ + publishAndLogTransfer( + request?: DeepPartial + ): Promise; /** * NextInternalKey derives the next internal key for the given key family and * stores it as an internal key in the database to make sure it is identified @@ -169,6 +385,17 @@ export interface AssetWallet { nextScriptKey( request?: DeepPartial ): Promise; + /** QueryInternalKey returns the key descriptor for the given internal key. */ + queryInternalKey( + request?: DeepPartial + ): Promise; + /** + * QueryScriptKey returns the full script key descriptor for the given tweaked + * script key. + */ + queryScriptKey( + request?: DeepPartial + ): Promise; /** * tapcli: `proofs proveownership` * ProveAssetOwnership creates an ownership proof embedded in an asset @@ -194,6 +421,15 @@ export interface AssetWallet { removeUTXOLease( request?: DeepPartial ): Promise; + /** + * DeclareScriptKey declares a new script key to the wallet. This is useful + * when the script key contains scripts, which would mean it wouldn't be + * recognized by the wallet automatically. Declaring a script key will make any + * assets sent to the script key be recognized as being local assets. + */ + declareScriptKey( + request?: DeepPartial + ): Promise; } type Builtin = diff --git a/lib/types/proto/tapd/lightning.ts b/lib/types/proto/tapd/lightning.ts new file mode 100644 index 0000000..de8a03c --- /dev/null +++ b/lib/types/proto/tapd/lightning.ts @@ -0,0 +1,4896 @@ +/* eslint-disable */ + +export enum OutputScriptType { + SCRIPT_TYPE_PUBKEY_HASH = 'SCRIPT_TYPE_PUBKEY_HASH', + SCRIPT_TYPE_SCRIPT_HASH = 'SCRIPT_TYPE_SCRIPT_HASH', + SCRIPT_TYPE_WITNESS_V0_PUBKEY_HASH = 'SCRIPT_TYPE_WITNESS_V0_PUBKEY_HASH', + SCRIPT_TYPE_WITNESS_V0_SCRIPT_HASH = 'SCRIPT_TYPE_WITNESS_V0_SCRIPT_HASH', + SCRIPT_TYPE_PUBKEY = 'SCRIPT_TYPE_PUBKEY', + SCRIPT_TYPE_MULTISIG = 'SCRIPT_TYPE_MULTISIG', + SCRIPT_TYPE_NULLDATA = 'SCRIPT_TYPE_NULLDATA', + SCRIPT_TYPE_NON_STANDARD = 'SCRIPT_TYPE_NON_STANDARD', + SCRIPT_TYPE_WITNESS_UNKNOWN = 'SCRIPT_TYPE_WITNESS_UNKNOWN', + SCRIPT_TYPE_WITNESS_V1_TAPROOT = 'SCRIPT_TYPE_WITNESS_V1_TAPROOT', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export enum CoinSelectionStrategy { + /** + * STRATEGY_USE_GLOBAL_CONFIG - Use the coin selection strategy defined in the global configuration + * (lnd.conf). + */ + STRATEGY_USE_GLOBAL_CONFIG = 'STRATEGY_USE_GLOBAL_CONFIG', + /** STRATEGY_LARGEST - Select the largest available coins first during coin selection. */ + STRATEGY_LARGEST = 'STRATEGY_LARGEST', + /** STRATEGY_RANDOM - Randomly select the available coins during coin selection. */ + STRATEGY_RANDOM = 'STRATEGY_RANDOM', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +/** + * `AddressType` has to be one of: + * + * - `p2wkh`: Pay to witness key hash (`WITNESS_PUBKEY_HASH` = 0) + * - `np2wkh`: Pay to nested witness key hash (`NESTED_PUBKEY_HASH` = 1) + * - `p2tr`: Pay to taproot pubkey (`TAPROOT_PUBKEY` = 4) + */ +export enum AddressType { + WITNESS_PUBKEY_HASH = 'WITNESS_PUBKEY_HASH', + NESTED_PUBKEY_HASH = 'NESTED_PUBKEY_HASH', + UNUSED_WITNESS_PUBKEY_HASH = 'UNUSED_WITNESS_PUBKEY_HASH', + UNUSED_NESTED_PUBKEY_HASH = 'UNUSED_NESTED_PUBKEY_HASH', + TAPROOT_PUBKEY = 'TAPROOT_PUBKEY', + UNUSED_TAPROOT_PUBKEY = 'UNUSED_TAPROOT_PUBKEY', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export enum CommitmentType { + /** UNKNOWN_COMMITMENT_TYPE - Returned when the commitment type isn't known or unavailable. */ + UNKNOWN_COMMITMENT_TYPE = 'UNKNOWN_COMMITMENT_TYPE', + /** + * LEGACY - A channel using the legacy commitment format having tweaked to_remote + * keys. + */ + LEGACY = 'LEGACY', + /** + * STATIC_REMOTE_KEY - A channel that uses the modern commitment format where the key in the + * output of the remote party does not change each state. This makes back + * up and recovery easier as when the channel is closed, the funds go + * directly to that key. + */ + STATIC_REMOTE_KEY = 'STATIC_REMOTE_KEY', + /** + * ANCHORS - A channel that uses a commitment format that has anchor outputs on the + * commitments, allowing fee bumping after a force close transaction has + * been broadcast. + */ + ANCHORS = 'ANCHORS', + /** + * SCRIPT_ENFORCED_LEASE - A channel that uses a commitment type that builds upon the anchors + * commitment format, but in addition requires a CLTV clause to spend outputs + * paying to the channel initiator. This is intended for use on leased channels + * to guarantee that the channel initiator has no incentives to close a leased + * channel before its maturity date. + */ + SCRIPT_ENFORCED_LEASE = 'SCRIPT_ENFORCED_LEASE', + /** + * SIMPLE_TAPROOT - A channel that uses musig2 for the funding output, and the new tapscript + * features where relevant. + */ + SIMPLE_TAPROOT = 'SIMPLE_TAPROOT', + /** + * SIMPLE_TAPROOT_OVERLAY - Identical to the SIMPLE_TAPROOT channel type, but with extra functionality. + * This channel type also commits to additional meta data in the tapscript + * leaves for the scripts in a channel. + */ + SIMPLE_TAPROOT_OVERLAY = 'SIMPLE_TAPROOT_OVERLAY', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export enum Initiator { + INITIATOR_UNKNOWN = 'INITIATOR_UNKNOWN', + INITIATOR_LOCAL = 'INITIATOR_LOCAL', + INITIATOR_REMOTE = 'INITIATOR_REMOTE', + INITIATOR_BOTH = 'INITIATOR_BOTH', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export enum ResolutionType { + TYPE_UNKNOWN = 'TYPE_UNKNOWN', + /** ANCHOR - We resolved an anchor output. */ + ANCHOR = 'ANCHOR', + /** + * INCOMING_HTLC - We are resolving an incoming htlc on chain. This if this htlc is + * claimed, we swept the incoming htlc with the preimage. If it is timed + * out, our peer swept the timeout path. + */ + INCOMING_HTLC = 'INCOMING_HTLC', + /** + * OUTGOING_HTLC - We are resolving an outgoing htlc on chain. If this htlc is claimed, + * the remote party swept the htlc with the preimage. If it is timed out, + * we swept it with the timeout path. + */ + OUTGOING_HTLC = 'OUTGOING_HTLC', + /** COMMIT - We force closed and need to sweep our time locked commitment output. */ + COMMIT = 'COMMIT', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export enum ResolutionOutcome { + /** OUTCOME_UNKNOWN - Outcome unknown. */ + OUTCOME_UNKNOWN = 'OUTCOME_UNKNOWN', + /** CLAIMED - An output was claimed on chain. */ + CLAIMED = 'CLAIMED', + /** UNCLAIMED - An output was left unclaimed on chain. */ + UNCLAIMED = 'UNCLAIMED', + /** + * ABANDONED - ResolverOutcomeAbandoned indicates that an output that we did not + * claim on chain, for example an anchor that we did not sweep and a + * third party claimed on chain, or a htlc that we could not decode + * so left unclaimed. + */ + ABANDONED = 'ABANDONED', + /** + * FIRST_STAGE - If we force closed our channel, our htlcs need to be claimed in two + * stages. This outcome represents the broadcast of a timeout or success + * transaction for this two stage htlc claim. + */ + FIRST_STAGE = 'FIRST_STAGE', + /** TIMEOUT - A htlc was timed out on chain. */ + TIMEOUT = 'TIMEOUT', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export enum NodeMetricType { + UNKNOWN = 'UNKNOWN', + BETWEENNESS_CENTRALITY = 'BETWEENNESS_CENTRALITY', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export enum InvoiceHTLCState { + ACCEPTED = 'ACCEPTED', + SETTLED = 'SETTLED', + CANCELED = 'CANCELED', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export enum PaymentFailureReason { + /** FAILURE_REASON_NONE - Payment isn't failed (yet). */ + FAILURE_REASON_NONE = 'FAILURE_REASON_NONE', + /** FAILURE_REASON_TIMEOUT - There are more routes to try, but the payment timeout was exceeded. */ + FAILURE_REASON_TIMEOUT = 'FAILURE_REASON_TIMEOUT', + /** + * FAILURE_REASON_NO_ROUTE - All possible routes were tried and failed permanently. Or were no + * routes to the destination at all. + */ + FAILURE_REASON_NO_ROUTE = 'FAILURE_REASON_NO_ROUTE', + /** FAILURE_REASON_ERROR - A non-recoverable error has occured. */ + FAILURE_REASON_ERROR = 'FAILURE_REASON_ERROR', + /** + * FAILURE_REASON_INCORRECT_PAYMENT_DETAILS - Payment details incorrect (unknown hash, invalid amt or + * invalid final cltv delta) + */ + FAILURE_REASON_INCORRECT_PAYMENT_DETAILS = 'FAILURE_REASON_INCORRECT_PAYMENT_DETAILS', + /** FAILURE_REASON_INSUFFICIENT_BALANCE - Insufficient local balance. */ + FAILURE_REASON_INSUFFICIENT_BALANCE = 'FAILURE_REASON_INSUFFICIENT_BALANCE', + /** FAILURE_REASON_CANCELED - The payment was canceled. */ + FAILURE_REASON_CANCELED = 'FAILURE_REASON_CANCELED', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export enum FeatureBit { + DATALOSS_PROTECT_REQ = 'DATALOSS_PROTECT_REQ', + DATALOSS_PROTECT_OPT = 'DATALOSS_PROTECT_OPT', + INITIAL_ROUING_SYNC = 'INITIAL_ROUING_SYNC', + UPFRONT_SHUTDOWN_SCRIPT_REQ = 'UPFRONT_SHUTDOWN_SCRIPT_REQ', + UPFRONT_SHUTDOWN_SCRIPT_OPT = 'UPFRONT_SHUTDOWN_SCRIPT_OPT', + GOSSIP_QUERIES_REQ = 'GOSSIP_QUERIES_REQ', + GOSSIP_QUERIES_OPT = 'GOSSIP_QUERIES_OPT', + TLV_ONION_REQ = 'TLV_ONION_REQ', + TLV_ONION_OPT = 'TLV_ONION_OPT', + EXT_GOSSIP_QUERIES_REQ = 'EXT_GOSSIP_QUERIES_REQ', + EXT_GOSSIP_QUERIES_OPT = 'EXT_GOSSIP_QUERIES_OPT', + STATIC_REMOTE_KEY_REQ = 'STATIC_REMOTE_KEY_REQ', + STATIC_REMOTE_KEY_OPT = 'STATIC_REMOTE_KEY_OPT', + PAYMENT_ADDR_REQ = 'PAYMENT_ADDR_REQ', + PAYMENT_ADDR_OPT = 'PAYMENT_ADDR_OPT', + MPP_REQ = 'MPP_REQ', + MPP_OPT = 'MPP_OPT', + WUMBO_CHANNELS_REQ = 'WUMBO_CHANNELS_REQ', + WUMBO_CHANNELS_OPT = 'WUMBO_CHANNELS_OPT', + ANCHORS_REQ = 'ANCHORS_REQ', + ANCHORS_OPT = 'ANCHORS_OPT', + ANCHORS_ZERO_FEE_HTLC_REQ = 'ANCHORS_ZERO_FEE_HTLC_REQ', + ANCHORS_ZERO_FEE_HTLC_OPT = 'ANCHORS_ZERO_FEE_HTLC_OPT', + ROUTE_BLINDING_REQUIRED = 'ROUTE_BLINDING_REQUIRED', + ROUTE_BLINDING_OPTIONAL = 'ROUTE_BLINDING_OPTIONAL', + AMP_REQ = 'AMP_REQ', + AMP_OPT = 'AMP_OPT', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export enum UpdateFailure { + UPDATE_FAILURE_UNKNOWN = 'UPDATE_FAILURE_UNKNOWN', + UPDATE_FAILURE_PENDING = 'UPDATE_FAILURE_PENDING', + UPDATE_FAILURE_NOT_FOUND = 'UPDATE_FAILURE_NOT_FOUND', + UPDATE_FAILURE_INTERNAL_ERR = 'UPDATE_FAILURE_INTERNAL_ERR', + UPDATE_FAILURE_INVALID_PARAMETER = 'UPDATE_FAILURE_INVALID_PARAMETER', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export interface LookupHtlcResolutionRequest { + chanId: string; + htlcIndex: string; +} + +export interface LookupHtlcResolutionResponse { + /** Settled is true is the htlc was settled. If false, the htlc was failed. */ + settled: boolean; + /** Offchain indicates whether the htlc was resolved off-chain or on-chain. */ + offchain: boolean; +} + +export interface SubscribeCustomMessagesRequest {} + +export interface CustomMessage { + /** Peer from which the message originates */ + peer: Uint8Array | string; + /** Message type. This value will be in the custom range (>= 32768). */ + type: number; + /** Raw message data */ + data: Uint8Array | string; +} + +export interface SendCustomMessageRequest { + /** Peer to send the message to */ + peer: Uint8Array | string; + /** + * Message type. This value needs to be in the custom range (>= 32768). + * To send a type < custom range, lnd needs to be compiled with the `dev` + * build tag, and the message type to override should be specified in lnd's + * experimental protocol configuration. + */ + type: number; + /** Raw message data. */ + data: Uint8Array | string; +} + +export interface SendCustomMessageResponse {} + +export interface Utxo { + /** The type of address */ + addressType: AddressType; + /** The address */ + address: string; + /** The value of the unspent coin in satoshis */ + amountSat: string; + /** The pkscript in hex */ + pkScript: string; + /** The outpoint in format txid:n */ + outpoint: OutPoint | undefined; + /** The number of confirmations for the Utxo */ + confirmations: string; +} + +export interface OutputDetail { + /** The type of the output */ + outputType: OutputScriptType; + /** The address */ + address: string; + /** The pkscript in hex */ + pkScript: string; + /** The output index used in the raw transaction */ + outputIndex: string; + /** The value of the output coin in satoshis */ + amount: string; + /** Denotes if the output is controlled by the internal wallet */ + isOurAddress: boolean; +} + +export interface Transaction { + /** The transaction hash */ + txHash: string; + /** The transaction amount, denominated in satoshis */ + amount: string; + /** The number of confirmations */ + numConfirmations: number; + /** The hash of the block this transaction was included in */ + blockHash: string; + /** The height of the block this transaction was included in */ + blockHeight: number; + /** Timestamp of this transaction */ + timeStamp: string; + /** Fees paid for this transaction */ + totalFees: string; + /** + * Addresses that received funds for this transaction. Deprecated as it is + * now incorporated in the output_details field. + * + * @deprecated + */ + destAddresses: string[]; + /** Outputs that received funds for this transaction */ + outputDetails: OutputDetail[]; + /** The raw transaction hex. */ + rawTxHex: string; + /** A label that was optionally set on transaction broadcast. */ + label: string; + /** PreviousOutpoints/Inputs of this transaction. */ + previousOutpoints: PreviousOutPoint[]; +} + +export interface GetTransactionsRequest { + /** + * The height from which to list transactions, inclusive. If this value is + * greater than end_height, transactions will be read in reverse. + */ + startHeight: number; + /** + * The height until which to list transactions, inclusive. To include + * unconfirmed transactions, this value should be set to -1, which will + * return transactions from start_height until the current chain tip and + * unconfirmed transactions. If no end_height is provided, the call will + * default to this option. + */ + endHeight: number; + /** An optional filter to only include transactions relevant to an account. */ + account: string; +} + +export interface TransactionDetails { + /** The list of transactions relevant to the wallet. */ + transactions: Transaction[]; +} + +export interface FeeLimit { + /** + * The fee limit expressed as a fixed amount of satoshis. + * + * The fields fixed and fixed_msat are mutually exclusive. + */ + fixed: string | undefined; + /** + * The fee limit expressed as a fixed amount of millisatoshis. + * + * The fields fixed and fixed_msat are mutually exclusive. + */ + fixedMsat: string | undefined; + /** The fee limit expressed as a percentage of the payment amount. */ + percent: string | undefined; +} + +export interface SendRequest { + /** + * The identity pubkey of the payment recipient. When using REST, this field + * must be encoded as base64. + */ + dest: Uint8Array | string; + /** + * The hex-encoded identity pubkey of the payment recipient. Deprecated now + * that the REST gateway supports base64 encoding of bytes fields. + * + * @deprecated + */ + destString: string; + /** + * The amount to send expressed in satoshis. + * + * The fields amt and amt_msat are mutually exclusive. + */ + amt: string; + /** + * The amount to send expressed in millisatoshis. + * + * The fields amt and amt_msat are mutually exclusive. + */ + amtMsat: string; + /** + * The hash to use within the payment's HTLC. When using REST, this field + * must be encoded as base64. + */ + paymentHash: Uint8Array | string; + /** + * The hex-encoded hash to use within the payment's HTLC. Deprecated now + * that the REST gateway supports base64 encoding of bytes fields. + * + * @deprecated + */ + paymentHashString: string; + /** + * A bare-bones invoice for a payment within the Lightning Network. With the + * details of the invoice, the sender has all the data necessary to send a + * payment to the recipient. + */ + paymentRequest: string; + /** + * The CLTV delta from the current height that should be used to set the + * timelock for the final hop. + */ + finalCltvDelta: number; + /** + * The maximum number of satoshis that will be paid as a fee of the payment. + * This value can be represented either as a percentage of the amount being + * sent, or as a fixed amount of the maximum fee the user is willing the pay to + * send the payment. If not specified, lnd will use a default value of 100% + * fees for small amounts (<=1k sat) or 5% fees for larger amounts. + */ + feeLimit: FeeLimit | undefined; + /** + * The channel id of the channel that must be taken to the first hop. If zero, + * any channel may be used. + */ + outgoingChanId: string; + /** The pubkey of the last hop of the route. If empty, any hop may be used. */ + lastHopPubkey: Uint8Array | string; + /** + * An optional maximum total time lock for the route. This should not exceed + * lnd's `--max-cltv-expiry` setting. If zero, then the value of + * `--max-cltv-expiry` is enforced. + */ + cltvLimit: number; + /** + * An optional field that can be used to pass an arbitrary set of TLV records + * to a peer which understands the new records. This can be used to pass + * application specific data during the payment attempt. Record types are + * required to be in the custom range >= 65536. When using REST, the values + * must be encoded as base64. + */ + destCustomRecords: { [key: string]: Uint8Array | string }; + /** If set, circular payments to self are permitted. */ + allowSelfPayment: boolean; + /** + * Features assumed to be supported by the final node. All transitive feature + * dependencies must also be set properly. For a given feature bit pair, either + * optional or remote may be set, but not both. If this field is nil or empty, + * the router will try to load destination features from the graph as a + * fallback. + */ + destFeatures: FeatureBit[]; + /** + * The payment address of the generated invoice. This is also called + * payment secret in specifications (e.g. BOLT 11). + */ + paymentAddr: Uint8Array | string; +} + +export interface SendRequest_DestCustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + +export interface SendResponse { + paymentError: string; + paymentPreimage: Uint8Array | string; + paymentRoute: Route | undefined; + paymentHash: Uint8Array | string; +} + +export interface SendToRouteRequest { + /** + * The payment hash to use for the HTLC. When using REST, this field must be + * encoded as base64. + */ + paymentHash: Uint8Array | string; + /** + * An optional hex-encoded payment hash to be used for the HTLC. Deprecated now + * that the REST gateway supports base64 encoding of bytes fields. + * + * @deprecated + */ + paymentHashString: string; + /** Route that should be used to attempt to complete the payment. */ + route: Route | undefined; +} + +export interface ChannelAcceptRequest { + /** The pubkey of the node that wishes to open an inbound channel. */ + nodePubkey: Uint8Array | string; + /** The hash of the genesis block that the proposed channel resides in. */ + chainHash: Uint8Array | string; + /** The pending channel id. */ + pendingChanId: Uint8Array | string; + /** + * The funding amount in satoshis that initiator wishes to use in the + * channel. + */ + fundingAmt: string; + /** The push amount of the proposed channel in millisatoshis. */ + pushAmt: string; + /** The dust limit of the initiator's commitment tx. */ + dustLimit: string; + /** + * The maximum amount of coins in millisatoshis that can be pending in this + * channel. + */ + maxValueInFlight: string; + /** + * The minimum amount of satoshis the initiator requires us to have at all + * times. + */ + channelReserve: string; + /** The smallest HTLC in millisatoshis that the initiator will accept. */ + minHtlc: string; + /** + * The initial fee rate that the initiator suggests for both commitment + * transactions. + */ + feePerKw: string; + /** + * The number of blocks to use for the relative time lock in the pay-to-self + * output of both commitment transactions. + */ + csvDelay: number; + /** The total number of incoming HTLC's that the initiator will accept. */ + maxAcceptedHtlcs: number; + /** + * A bit-field which the initiator uses to specify proposed channel + * behavior. + */ + channelFlags: number; + /** The commitment type the initiator wishes to use for the proposed channel. */ + commitmentType: CommitmentType; + /** + * Whether the initiator wants to open a zero-conf channel via the channel + * type. + */ + wantsZeroConf: boolean; + /** + * Whether the initiator wants to use the scid-alias channel type. This is + * separate from the feature bit. + */ + wantsScidAlias: boolean; +} + +export interface ChannelAcceptResponse { + /** Whether or not the client accepts the channel. */ + accept: boolean; + /** The pending channel id to which this response applies. */ + pendingChanId: Uint8Array | string; + /** + * An optional error to send the initiating party to indicate why the channel + * was rejected. This field *should not* contain sensitive information, it will + * be sent to the initiating party. This field should only be set if accept is + * false, the channel will be rejected if an error is set with accept=true + * because the meaning of this response is ambiguous. Limited to 500 + * characters. + */ + error: string; + /** + * The upfront shutdown address to use if the initiating peer supports option + * upfront shutdown script (see ListPeers for the features supported). Note + * that the channel open will fail if this value is set for a peer that does + * not support this feature bit. + */ + upfrontShutdown: string; + /** The csv delay (in blocks) that we require for the remote party. */ + csvDelay: number; + /** + * The reserve amount in satoshis that we require the remote peer to adhere to. + * We require that the remote peer always have some reserve amount allocated to + * them so that there is always a disincentive to broadcast old state (if they + * hold 0 sats on their side of the channel, there is nothing to lose). + */ + reserveSat: string; + /** + * The maximum amount of funds in millisatoshis that we allow the remote peer + * to have in outstanding htlcs. + */ + inFlightMaxMsat: string; + /** The maximum number of htlcs that the remote peer can offer us. */ + maxHtlcCount: number; + /** The minimum value in millisatoshis for incoming htlcs on the channel. */ + minHtlcIn: string; + /** The number of confirmations we require before we consider the channel open. */ + minAcceptDepth: number; + /** + * Whether the responder wants this to be a zero-conf channel. This will fail + * if either side does not have the scid-alias feature bit set. The minimum + * depth field must be zero if this is true. + */ + zeroConf: boolean; +} + +export interface ChannelPoint { + /** + * Txid of the funding transaction. When using REST, this field must be + * encoded as base64. + */ + fundingTxidBytes: Uint8Array | string | undefined; + /** + * Hex-encoded string representing the byte-reversed hash of the funding + * transaction. + */ + fundingTxidStr: string | undefined; + /** The index of the output of the funding transaction */ + outputIndex: number; +} + +export interface OutPoint { + /** Raw bytes representing the transaction id. */ + txidBytes: Uint8Array | string; + /** Reversed, hex-encoded string representing the transaction id. */ + txidStr: string; + /** The index of the output on the transaction. */ + outputIndex: number; +} + +export interface PreviousOutPoint { + /** The outpoint in format txid:n. */ + outpoint: string; + /** + * Denotes if the outpoint is controlled by the internal wallet. + * The flag will only detect p2wkh, np2wkh and p2tr inputs as its own. + */ + isOurOutput: boolean; +} + +export interface LightningAddress { + /** The identity pubkey of the Lightning node. */ + pubkey: string; + /** + * The network location of the lightning node, e.g. `69.69.69.69:1337` or + * `localhost:10011`. + */ + host: string; +} + +export interface EstimateFeeRequest { + /** The map from addresses to amounts for the transaction. */ + AddrToAmount: { [key: string]: string }; + /** + * The target number of blocks that this transaction should be confirmed + * by. + */ + targetConf: number; + /** + * The minimum number of confirmations each one of your outputs used for + * the transaction must satisfy. + */ + minConfs: number; + /** Whether unconfirmed outputs should be used as inputs for the transaction. */ + spendUnconfirmed: boolean; + /** The strategy to use for selecting coins during fees estimation. */ + coinSelectionStrategy: CoinSelectionStrategy; +} + +export interface EstimateFeeRequest_AddrToAmountEntry { + key: string; + value: string; +} + +export interface EstimateFeeResponse { + /** The total fee in satoshis. */ + feeSat: string; + /** + * Deprecated, use sat_per_vbyte. + * The fee rate in satoshi/vbyte. + * + * @deprecated + */ + feerateSatPerByte: string; + /** The fee rate in satoshi/vbyte. */ + satPerVbyte: string; +} + +export interface SendManyRequest { + /** The map from addresses to amounts */ + AddrToAmount: { [key: string]: string }; + /** + * The target number of blocks that this transaction should be confirmed + * by. + */ + targetConf: number; + /** + * A manual fee rate set in sat/vbyte that should be used when crafting the + * transaction. + */ + satPerVbyte: string; + /** + * Deprecated, use sat_per_vbyte. + * A manual fee rate set in sat/vbyte that should be used when crafting the + * transaction. + * + * @deprecated + */ + satPerByte: string; + /** An optional label for the transaction, limited to 500 characters. */ + label: string; + /** + * The minimum number of confirmations each one of your outputs used for + * the transaction must satisfy. + */ + minConfs: number; + /** Whether unconfirmed outputs should be used as inputs for the transaction. */ + spendUnconfirmed: boolean; + /** The strategy to use for selecting coins during sending many requests. */ + coinSelectionStrategy: CoinSelectionStrategy; +} + +export interface SendManyRequest_AddrToAmountEntry { + key: string; + value: string; +} + +export interface SendManyResponse { + /** The id of the transaction */ + txid: string; +} + +export interface SendCoinsRequest { + /** The address to send coins to */ + addr: string; + /** The amount in satoshis to send */ + amount: string; + /** + * The target number of blocks that this transaction should be confirmed + * by. + */ + targetConf: number; + /** + * A manual fee rate set in sat/vbyte that should be used when crafting the + * transaction. + */ + satPerVbyte: string; + /** + * Deprecated, use sat_per_vbyte. + * A manual fee rate set in sat/vbyte that should be used when crafting the + * transaction. + * + * @deprecated + */ + satPerByte: string; + /** + * If set, the amount field should be unset. It indicates lnd will send all + * wallet coins or all selected coins to the specified address. + */ + sendAll: boolean; + /** An optional label for the transaction, limited to 500 characters. */ + label: string; + /** + * The minimum number of confirmations each one of your outputs used for + * the transaction must satisfy. + */ + minConfs: number; + /** Whether unconfirmed outputs should be used as inputs for the transaction. */ + spendUnconfirmed: boolean; + /** The strategy to use for selecting coins. */ + coinSelectionStrategy: CoinSelectionStrategy; + /** A list of selected outpoints as inputs for the transaction. */ + outpoints: OutPoint[]; +} + +export interface SendCoinsResponse { + /** The transaction ID of the transaction */ + txid: string; +} + +export interface ListUnspentRequest { + /** The minimum number of confirmations to be included. */ + minConfs: number; + /** The maximum number of confirmations to be included. */ + maxConfs: number; + /** An optional filter to only include outputs belonging to an account. */ + account: string; +} + +export interface ListUnspentResponse { + /** A list of utxos */ + utxos: Utxo[]; +} + +export interface NewAddressRequest { + /** The type of address to generate. */ + type: AddressType; + /** + * The name of the account to generate a new address for. If empty, the + * default wallet account is used. + */ + account: string; +} + +export interface NewAddressResponse { + /** The newly generated wallet address */ + address: string; +} + +export interface SignMessageRequest { + /** + * The message to be signed. When using REST, this field must be encoded as + * base64. + */ + msg: Uint8Array | string; + /** + * Instead of the default double-SHA256 hashing of the message before signing, + * only use one round of hashing instead. + */ + singleHash: boolean; +} + +export interface SignMessageResponse { + /** The signature for the given message */ + signature: string; +} + +export interface VerifyMessageRequest { + /** + * The message over which the signature is to be verified. When using REST, + * this field must be encoded as base64. + */ + msg: Uint8Array | string; + /** The signature to be verified over the given message */ + signature: string; +} + +export interface VerifyMessageResponse { + /** Whether the signature was valid over the given message */ + valid: boolean; + /** The pubkey recovered from the signature */ + pubkey: string; +} + +export interface ConnectPeerRequest { + /** Lightning address of the peer to connect to. */ + addr: LightningAddress | undefined; + /** + * If set, the daemon will attempt to persistently connect to the target + * peer. Otherwise, the call will be synchronous. + */ + perm: boolean; + /** + * The connection timeout value (in seconds) for this request. It won't affect + * other requests. + */ + timeout: string; +} + +export interface ConnectPeerResponse {} + +export interface DisconnectPeerRequest { + /** The pubkey of the node to disconnect from */ + pubKey: string; +} + +export interface DisconnectPeerResponse {} + +export interface HTLC { + incoming: boolean; + amount: string; + hashLock: Uint8Array | string; + expirationHeight: number; + /** Index identifying the htlc on the channel. */ + htlcIndex: string; + /** + * If this HTLC is involved in a forwarding operation, this field indicates + * the forwarding channel. For an outgoing htlc, it is the incoming channel. + * For an incoming htlc, it is the outgoing channel. When the htlc + * originates from this node or this node is the final destination, + * forwarding_channel will be zero. The forwarding channel will also be zero + * for htlcs that need to be forwarded but don't have a forwarding decision + * persisted yet. + */ + forwardingChannel: string; + /** Index identifying the htlc on the forwarding channel. */ + forwardingHtlcIndex: string; +} + +export interface ChannelConstraints { + /** + * The CSV delay expressed in relative blocks. If the channel is force closed, + * we will need to wait for this many blocks before we can regain our funds. + */ + csvDelay: number; + /** The minimum satoshis this node is required to reserve in its balance. */ + chanReserveSat: string; + /** The dust limit (in satoshis) of the initiator's commitment tx. */ + dustLimitSat: string; + /** + * The maximum amount of coins in millisatoshis that can be pending in this + * channel. + */ + maxPendingAmtMsat: string; + /** The smallest HTLC in millisatoshis that the initiator will accept. */ + minHtlcMsat: string; + /** The total number of incoming HTLC's that the initiator will accept. */ + maxAcceptedHtlcs: number; +} + +export interface Channel { + /** Whether this channel is active or not */ + active: boolean; + /** The identity pubkey of the remote node */ + remotePubkey: string; + /** + * The outpoint (txid:index) of the funding transaction. With this value, Bob + * will be able to generate a signature for Alice's version of the commitment + * transaction. + */ + channelPoint: string; + /** + * The unique channel ID for the channel. The first 3 bytes are the block + * height, the next 3 the index within the block, and the last 2 bytes are the + * output index for the channel. + */ + chanId: string; + /** The total amount of funds held in this channel */ + capacity: string; + /** This node's current balance in this channel */ + localBalance: string; + /** The counterparty's current balance in this channel */ + remoteBalance: string; + /** + * The amount calculated to be paid in fees for the current set of commitment + * transactions. The fee amount is persisted with the channel in order to + * allow the fee amount to be removed and recalculated with each channel state + * update, including updates that happen after a system restart. + */ + commitFee: string; + /** The weight of the commitment transaction */ + commitWeight: string; + /** + * The required number of satoshis per kilo-weight that the requester will pay + * at all times, for both the funding transaction and commitment transaction. + * This value can later be updated once the channel is open. + */ + feePerKw: string; + /** The unsettled balance in this channel */ + unsettledBalance: string; + /** The total number of satoshis we've sent within this channel. */ + totalSatoshisSent: string; + /** The total number of satoshis we've received within this channel. */ + totalSatoshisReceived: string; + /** The total number of updates conducted within this channel. */ + numUpdates: string; + /** The list of active, uncleared HTLCs currently pending within the channel. */ + pendingHtlcs: HTLC[]; + /** + * Deprecated. The CSV delay expressed in relative blocks. If the channel is + * force closed, we will need to wait for this many blocks before we can regain + * our funds. + * + * @deprecated + */ + csvDelay: number; + /** Whether this channel is advertised to the network or not. */ + private: boolean; + /** True if we were the ones that created the channel. */ + initiator: boolean; + /** A set of flags showing the current state of the channel. */ + chanStatusFlags: string; + /** + * Deprecated. The minimum satoshis this node is required to reserve in its + * balance. + * + * @deprecated + */ + localChanReserveSat: string; + /** + * Deprecated. The minimum satoshis the other node is required to reserve in + * its balance. + * + * @deprecated + */ + remoteChanReserveSat: string; + /** + * Deprecated. Use commitment_type. + * + * @deprecated + */ + staticRemoteKey: boolean; + /** The commitment type used by this channel. */ + commitmentType: CommitmentType; + /** + * The number of seconds that the channel has been monitored by the channel + * scoring system. Scores are currently not persisted, so this value may be + * less than the lifetime of the channel [EXPERIMENTAL]. + */ + lifetime: string; + /** + * The number of seconds that the remote peer has been observed as being online + * by the channel scoring system over the lifetime of the channel + * [EXPERIMENTAL]. + */ + uptime: string; + /** + * Close address is the address that we will enforce payout to on cooperative + * close if the channel was opened utilizing option upfront shutdown. This + * value can be set on channel open by setting close_address in an open channel + * request. If this value is not set, you can still choose a payout address by + * cooperatively closing with the delivery_address field set. + */ + closeAddress: string; + /** + * The amount that the initiator of the channel optionally pushed to the remote + * party on channel open. This amount will be zero if the channel initiator did + * not push any funds to the remote peer. If the initiator field is true, we + * pushed this amount to our peer, if it is false, the remote peer pushed this + * amount to us. + */ + pushAmountSat: string; + /** + * This uint32 indicates if this channel is to be considered 'frozen'. A + * frozen channel doest not allow a cooperative channel close by the + * initiator. The thaw_height is the height that this restriction stops + * applying to the channel. This field is optional, not setting it or using a + * value of zero will mean the channel has no additional restrictions. The + * height can be interpreted in two ways: as a relative height if the value is + * less than 500,000, or as an absolute height otherwise. + */ + thawHeight: number; + /** List constraints for the local node. */ + localConstraints: ChannelConstraints | undefined; + /** List constraints for the remote node. */ + remoteConstraints: ChannelConstraints | undefined; + /** + * This lists out the set of alias short channel ids that exist for a channel. + * This may be empty. + */ + aliasScids: string[]; + /** Whether or not this is a zero-conf channel. */ + zeroConf: boolean; + /** This is the confirmed / on-chain zero-conf SCID. */ + zeroConfConfirmedScid: string; + /** The configured alias name of our peer. */ + peerAlias: string; + /** This is the peer SCID alias. */ + peerScidAlias: string; + /** + * An optional note-to-self to go along with the channel containing some + * useful information. This is only ever stored locally and in no way impacts + * the channel's operation. + */ + memo: string; + /** Custom channel data that might be populated in custom channels. */ + customChannelData: Uint8Array | string; +} + +export interface ListChannelsRequest { + activeOnly: boolean; + inactiveOnly: boolean; + publicOnly: boolean; + privateOnly: boolean; + /** + * Filters the response for channels with a target peer's pubkey. If peer is + * empty, all channels will be returned. + */ + peer: Uint8Array | string; + /** + * Informs the server if the peer alias lookup per channel should be + * enabled. It is turned off by default in order to avoid degradation of + * performance for existing clients. + */ + peerAliasLookup: boolean; +} + +export interface ListChannelsResponse { + /** The list of active channels */ + channels: Channel[]; +} + +export interface AliasMap { + /** + * For non-zero-conf channels, this is the confirmed SCID. Otherwise, this is + * the first assigned "base" alias. + */ + baseScid: string; + /** The set of all aliases stored for the base SCID. */ + aliases: string[]; +} + +export interface ListAliasesRequest {} + +export interface ListAliasesResponse { + aliasMaps: AliasMap[]; +} + +export interface ChannelCloseSummary { + /** The outpoint (txid:index) of the funding transaction. */ + channelPoint: string; + /** The unique channel ID for the channel. */ + chanId: string; + /** The hash of the genesis block that this channel resides within. */ + chainHash: string; + /** The txid of the transaction which ultimately closed this channel. */ + closingTxHash: string; + /** Public key of the remote peer that we formerly had a channel with. */ + remotePubkey: string; + /** Total capacity of the channel. */ + capacity: string; + /** Height at which the funding transaction was spent. */ + closeHeight: number; + /** Settled balance at the time of channel closure */ + settledBalance: string; + /** The sum of all the time-locked outputs at the time of channel closure */ + timeLockedBalance: string; + /** Details on how the channel was closed. */ + closeType: ChannelCloseSummary_ClosureType; + /** + * Open initiator is the party that initiated opening the channel. Note that + * this value may be unknown if the channel was closed before we migrated to + * store open channel information after close. + */ + openInitiator: Initiator; + /** + * Close initiator indicates which party initiated the close. This value will + * be unknown for channels that were cooperatively closed before we started + * tracking cooperative close initiators. Note that this indicates which party + * initiated a close, and it is possible for both to initiate cooperative or + * force closes, although only one party's close will be confirmed on chain. + */ + closeInitiator: Initiator; + resolutions: Resolution[]; + /** + * This lists out the set of alias short channel ids that existed for the + * closed channel. This may be empty. + */ + aliasScids: string[]; + /** The confirmed SCID for a zero-conf channel. */ + zeroConfConfirmedScid: string; +} + +export enum ChannelCloseSummary_ClosureType { + COOPERATIVE_CLOSE = 'COOPERATIVE_CLOSE', + LOCAL_FORCE_CLOSE = 'LOCAL_FORCE_CLOSE', + REMOTE_FORCE_CLOSE = 'REMOTE_FORCE_CLOSE', + BREACH_CLOSE = 'BREACH_CLOSE', + FUNDING_CANCELED = 'FUNDING_CANCELED', + ABANDONED = 'ABANDONED', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export interface Resolution { + /** The type of output we are resolving. */ + resolutionType: ResolutionType; + /** The outcome of our on chain action that resolved the outpoint. */ + outcome: ResolutionOutcome; + /** The outpoint that was spent by the resolution. */ + outpoint: OutPoint | undefined; + /** The amount that was claimed by the resolution. */ + amountSat: string; + /** + * The hex-encoded transaction ID of the sweep transaction that spent the + * output. + */ + sweepTxid: string; +} + +export interface ClosedChannelsRequest { + cooperative: boolean; + localForce: boolean; + remoteForce: boolean; + breach: boolean; + fundingCanceled: boolean; + abandoned: boolean; +} + +export interface ClosedChannelsResponse { + channels: ChannelCloseSummary[]; +} + +export interface Peer { + /** The identity pubkey of the peer */ + pubKey: string; + /** Network address of the peer; eg `127.0.0.1:10011` */ + address: string; + /** Bytes of data transmitted to this peer */ + bytesSent: string; + /** Bytes of data transmitted from this peer */ + bytesRecv: string; + /** Satoshis sent to this peer */ + satSent: string; + /** Satoshis received from this peer */ + satRecv: string; + /** A channel is inbound if the counterparty initiated the channel */ + inbound: boolean; + /** Ping time to this peer */ + pingTime: string; + /** The type of sync we are currently performing with this peer. */ + syncType: Peer_SyncType; + /** Features advertised by the remote peer in their init message. */ + features: { [key: number]: Feature }; + /** + * The latest errors received from our peer with timestamps, limited to the 10 + * most recent errors. These errors are tracked across peer connections, but + * are not persisted across lnd restarts. Note that these errors are only + * stored for peers that we have channels open with, to prevent peers from + * spamming us with errors at no cost. + */ + errors: TimestampedError[]; + /** + * The number of times we have recorded this peer going offline or coming + * online, recorded across restarts. Note that this value is decreased over + * time if the peer has not recently flapped, so that we can forgive peers + * with historically high flap counts. + */ + flapCount: number; + /** + * The timestamp of the last flap we observed for this peer. If this value is + * zero, we have not observed any flaps for this peer. + */ + lastFlapNs: string; + /** The last ping payload the peer has sent to us. */ + lastPingPayload: Uint8Array | string; +} + +export enum Peer_SyncType { + /** UNKNOWN_SYNC - Denotes that we cannot determine the peer's current sync type. */ + UNKNOWN_SYNC = 'UNKNOWN_SYNC', + /** ACTIVE_SYNC - Denotes that we are actively receiving new graph updates from the peer. */ + ACTIVE_SYNC = 'ACTIVE_SYNC', + /** PASSIVE_SYNC - Denotes that we are not receiving new graph updates from the peer. */ + PASSIVE_SYNC = 'PASSIVE_SYNC', + /** PINNED_SYNC - Denotes that this peer is pinned into an active sync. */ + PINNED_SYNC = 'PINNED_SYNC', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export interface Peer_FeaturesEntry { + key: number; + value: Feature | undefined; +} + +export interface TimestampedError { + /** The unix timestamp in seconds when the error occurred. */ + timestamp: string; + /** The string representation of the error sent by our peer. */ + error: string; +} + +export interface ListPeersRequest { + /** + * If true, only the last error that our peer sent us will be returned with + * the peer's information, rather than the full set of historic errors we have + * stored. + */ + latestError: boolean; +} + +export interface ListPeersResponse { + /** The list of currently connected peers */ + peers: Peer[]; +} + +export interface PeerEventSubscription {} + +export interface PeerEvent { + /** The identity pubkey of the peer. */ + pubKey: string; + type: PeerEvent_EventType; +} + +export enum PeerEvent_EventType { + PEER_ONLINE = 'PEER_ONLINE', + PEER_OFFLINE = 'PEER_OFFLINE', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export interface GetInfoRequest {} + +export interface GetInfoResponse { + /** The version of the LND software that the node is running. */ + version: string; + /** The SHA1 commit hash that the daemon is compiled with. */ + commitHash: string; + /** The identity pubkey of the current node. */ + identityPubkey: string; + /** If applicable, the alias of the current node, e.g. "bob" */ + alias: string; + /** The color of the current node in hex code format */ + color: string; + /** Number of pending channels */ + numPendingChannels: number; + /** Number of active channels */ + numActiveChannels: number; + /** Number of inactive channels */ + numInactiveChannels: number; + /** Number of peers */ + numPeers: number; + /** The node's current view of the height of the best block */ + blockHeight: number; + /** The node's current view of the hash of the best block */ + blockHash: string; + /** Timestamp of the block best known to the wallet */ + bestHeaderTimestamp: string; + /** Whether the wallet's view is synced to the main chain */ + syncedToChain: boolean; + /** Whether we consider ourselves synced with the public channel graph. */ + syncedToGraph: boolean; + /** + * Whether the current node is connected to testnet. This field is + * deprecated and the network field should be used instead + * + * @deprecated + */ + testnet: boolean; + /** + * A list of active chains the node is connected to. This will only + * ever contain a single entry since LND will only ever have a single + * chain backend during its lifetime. + */ + chains: Chain[]; + /** The URIs of the current node. */ + uris: string[]; + /** + * Features that our node has advertised in our init message, node + * announcements and invoices. + */ + features: { [key: number]: Feature }; + /** Indicates whether the HTLC interceptor API is in always-on mode. */ + requireHtlcInterceptor: boolean; + /** Indicates whether final htlc resolutions are stored on disk. */ + storeFinalHtlcResolutions: boolean; +} + +export interface GetInfoResponse_FeaturesEntry { + key: number; + value: Feature | undefined; +} + +export interface GetDebugInfoRequest {} + +export interface GetDebugInfoResponse { + config: { [key: string]: string }; + log: string[]; +} + +export interface GetDebugInfoResponse_ConfigEntry { + key: string; + value: string; +} + +export interface GetRecoveryInfoRequest {} + +export interface GetRecoveryInfoResponse { + /** Whether the wallet is in recovery mode */ + recoveryMode: boolean; + /** Whether the wallet recovery progress is finished */ + recoveryFinished: boolean; + /** The recovery progress, ranging from 0 to 1. */ + progress: number; +} + +export interface Chain { + /** + * Deprecated. The chain is now always assumed to be bitcoin. + * The blockchain the node is on (must be bitcoin) + * + * @deprecated + */ + chain: string; + /** The network the node is on (eg regtest, testnet, mainnet) */ + network: string; +} + +export interface ConfirmationUpdate { + blockSha: Uint8Array | string; + blockHeight: number; + numConfsLeft: number; +} + +export interface ChannelOpenUpdate { + channelPoint: ChannelPoint | undefined; +} + +export interface CloseOutput { + /** + * The amount in satoshi of this close output. This amount is the final + * commitment balance of the channel and the actual amount paid out on chain + * might be smaller due to subtracted fees. + */ + amountSat: string; + /** The pkScript of the close output. */ + pkScript: Uint8Array | string; + /** Whether this output is for the local or remote node. */ + isLocal: boolean; + /** + * The TLV encoded custom channel data records for this output, which might + * be set for custom channels. + */ + customChannelData: Uint8Array | string; +} + +export interface ChannelCloseUpdate { + closingTxid: Uint8Array | string; + success: boolean; + /** + * The local channel close output. If the local channel balance was dust to + * begin with, this output will not be set. + */ + localCloseOutput: CloseOutput | undefined; + /** + * The remote channel close output. If the remote channel balance was dust + * to begin with, this output will not be set. + */ + remoteCloseOutput: CloseOutput | undefined; + /** Any additional outputs that might be added for custom channel types. */ + additionalOutputs: CloseOutput[]; +} + +export interface CloseChannelRequest { + /** + * The outpoint (txid:index) of the funding transaction. With this value, Bob + * will be able to generate a signature for Alice's version of the commitment + * transaction. + */ + channelPoint: ChannelPoint | undefined; + /** + * If true, then the channel will be closed forcibly. This means the + * current commitment transaction will be signed and broadcast. + */ + force: boolean; + /** + * The target number of blocks that the closure transaction should be + * confirmed by. + */ + targetConf: number; + /** + * Deprecated, use sat_per_vbyte. + * A manual fee rate set in sat/vbyte that should be used when crafting the + * closure transaction. + * + * @deprecated + */ + satPerByte: string; + /** + * An optional address to send funds to in the case of a cooperative close. + * If the channel was opened with an upfront shutdown script and this field + * is set, the request to close will fail because the channel must pay out + * to the upfront shutdown addresss. + */ + deliveryAddress: string; + /** + * A manual fee rate set in sat/vbyte that should be used when crafting the + * closure transaction. + */ + satPerVbyte: string; + /** + * The maximum fee rate the closer is willing to pay. + * + * NOTE: This field is only respected if we're the initiator of the channel. + */ + maxFeePerVbyte: string; + /** + * If true, then the rpc call will not block while it awaits a closing txid. + * Consequently this RPC call will not return a closing txid if this value + * is set. + */ + noWait: boolean; +} + +export interface CloseStatusUpdate { + closePending: PendingUpdate | undefined; + chanClose: ChannelCloseUpdate | undefined; + closeInstant: InstantUpdate | undefined; +} + +export interface PendingUpdate { + txid: Uint8Array | string; + outputIndex: number; +} + +export interface InstantUpdate {} + +export interface ReadyForPsbtFunding { + /** + * The P2WSH address of the channel funding multisig address that the below + * specified amount in satoshis needs to be sent to. + */ + fundingAddress: string; + /** + * The exact amount in satoshis that needs to be sent to the above address to + * fund the pending channel. + */ + fundingAmount: string; + /** + * A raw PSBT that contains the pending channel output. If a base PSBT was + * provided in the PsbtShim, this is the base PSBT with one additional output. + * If no base PSBT was specified, this is an otherwise empty PSBT with exactly + * one output. + */ + psbt: Uint8Array | string; +} + +export interface BatchOpenChannelRequest { + /** The list of channels to open. */ + channels: BatchOpenChannel[]; + /** + * The target number of blocks that the funding transaction should be + * confirmed by. + */ + targetConf: number; + /** + * A manual fee rate set in sat/vByte that should be used when crafting the + * funding transaction. + */ + satPerVbyte: string; + /** + * The minimum number of confirmations each one of your outputs used for + * the funding transaction must satisfy. + */ + minConfs: number; + /** + * Whether unconfirmed outputs should be used as inputs for the funding + * transaction. + */ + spendUnconfirmed: boolean; + /** An optional label for the batch transaction, limited to 500 characters. */ + label: string; + /** The strategy to use for selecting coins during batch opening channels. */ + coinSelectionStrategy: CoinSelectionStrategy; +} + +export interface BatchOpenChannel { + /** + * The pubkey of the node to open a channel with. When using REST, this + * field must be encoded as base64. + */ + nodePubkey: Uint8Array | string; + /** The number of satoshis the wallet should commit to the channel. */ + localFundingAmount: string; + /** + * The number of satoshis to push to the remote side as part of the initial + * commitment state. + */ + pushSat: string; + /** + * Whether this channel should be private, not announced to the greater + * network. + */ + private: boolean; + /** + * The minimum value in millisatoshi we will require for incoming HTLCs on + * the channel. + */ + minHtlcMsat: string; + /** + * The delay we require on the remote's commitment transaction. If this is + * not set, it will be scaled automatically with the channel size. + */ + remoteCsvDelay: number; + /** + * Close address is an optional address which specifies the address to which + * funds should be paid out to upon cooperative close. This field may only be + * set if the peer supports the option upfront feature bit (call listpeers + * to check). The remote peer will only accept cooperative closes to this + * address if it is set. + * + * Note: If this value is set on channel creation, you will *not* be able to + * cooperatively close out to a different address. + */ + closeAddress: string; + /** + * An optional, unique identifier of 32 random bytes that will be used as the + * pending channel ID to identify the channel while it is in the pre-pending + * state. + */ + pendingChanId: Uint8Array | string; + /** + * The explicit commitment type to use. Note this field will only be used if + * the remote peer supports explicit channel negotiation. + */ + commitmentType: CommitmentType; + /** + * The maximum amount of coins in millisatoshi that can be pending within + * the channel. It only applies to the remote party. + */ + remoteMaxValueInFlightMsat: string; + /** + * The maximum number of concurrent HTLCs we will allow the remote party to add + * to the commitment transaction. + */ + remoteMaxHtlcs: number; + /** + * Max local csv is the maximum csv delay we will allow for our own commitment + * transaction. + */ + maxLocalCsv: number; + /** If this is true, then a zero-conf channel open will be attempted. */ + zeroConf: boolean; + /** + * If this is true, then an option-scid-alias channel-type open will be + * attempted. + */ + scidAlias: boolean; + /** The base fee charged regardless of the number of milli-satoshis sent. */ + baseFee: string; + /** + * The fee rate in ppm (parts per million) that will be charged in + * proportion of the value of each forwarded HTLC. + */ + feeRate: string; + /** + * If use_base_fee is true the open channel announcement will update the + * channel base fee with the value specified in base_fee. In the case of + * a base_fee of 0 use_base_fee is needed downstream to distinguish whether + * to use the default base fee value specified in the config or 0. + */ + useBaseFee: boolean; + /** + * If use_fee_rate is true the open channel announcement will update the + * channel fee rate with the value specified in fee_rate. In the case of + * a fee_rate of 0 use_fee_rate is needed downstream to distinguish whether + * to use the default fee rate value specified in the config or 0. + */ + useFeeRate: boolean; + /** + * The number of satoshis we require the remote peer to reserve. This value, + * if specified, must be above the dust limit and below 20% of the channel + * capacity. + */ + remoteChanReserveSat: string; + /** + * An optional note-to-self to go along with the channel containing some + * useful information. This is only ever stored locally and in no way impacts + * the channel's operation. + */ + memo: string; +} + +export interface BatchOpenChannelResponse { + pendingChannels: PendingUpdate[]; +} + +export interface OpenChannelRequest { + /** + * A manual fee rate set in sat/vbyte that should be used when crafting the + * funding transaction. + */ + satPerVbyte: string; + /** + * The pubkey of the node to open a channel with. When using REST, this field + * must be encoded as base64. + */ + nodePubkey: Uint8Array | string; + /** + * The hex encoded pubkey of the node to open a channel with. Deprecated now + * that the REST gateway supports base64 encoding of bytes fields. + * + * @deprecated + */ + nodePubkeyString: string; + /** The number of satoshis the wallet should commit to the channel */ + localFundingAmount: string; + /** + * The number of satoshis to push to the remote side as part of the initial + * commitment state + */ + pushSat: string; + /** + * The target number of blocks that the funding transaction should be + * confirmed by. + */ + targetConf: number; + /** + * Deprecated, use sat_per_vbyte. + * A manual fee rate set in sat/vbyte that should be used when crafting the + * funding transaction. + * + * @deprecated + */ + satPerByte: string; + /** + * Whether this channel should be private, not announced to the greater + * network. + */ + private: boolean; + /** + * The minimum value in millisatoshi we will require for incoming HTLCs on + * the channel. + */ + minHtlcMsat: string; + /** + * The delay we require on the remote's commitment transaction. If this is + * not set, it will be scaled automatically with the channel size. + */ + remoteCsvDelay: number; + /** + * The minimum number of confirmations each one of your outputs used for + * the funding transaction must satisfy. + */ + minConfs: number; + /** + * Whether unconfirmed outputs should be used as inputs for the funding + * transaction. + */ + spendUnconfirmed: boolean; + /** + * Close address is an optional address which specifies the address to which + * funds should be paid out to upon cooperative close. This field may only be + * set if the peer supports the option upfront feature bit (call listpeers + * to check). The remote peer will only accept cooperative closes to this + * address if it is set. + * + * Note: If this value is set on channel creation, you will *not* be able to + * cooperatively close out to a different address. + */ + closeAddress: string; + /** + * Funding shims are an optional argument that allow the caller to intercept + * certain funding functionality. For example, a shim can be provided to use a + * particular key for the commitment key (ideally cold) rather than use one + * that is generated by the wallet as normal, or signal that signing will be + * carried out in an interactive manner (PSBT based). + */ + fundingShim: FundingShim | undefined; + /** + * The maximum amount of coins in millisatoshi that can be pending within + * the channel. It only applies to the remote party. + */ + remoteMaxValueInFlightMsat: string; + /** + * The maximum number of concurrent HTLCs we will allow the remote party to add + * to the commitment transaction. + */ + remoteMaxHtlcs: number; + /** + * Max local csv is the maximum csv delay we will allow for our own commitment + * transaction. + */ + maxLocalCsv: number; + /** + * The explicit commitment type to use. Note this field will only be used if + * the remote peer supports explicit channel negotiation. + */ + commitmentType: CommitmentType; + /** If this is true, then a zero-conf channel open will be attempted. */ + zeroConf: boolean; + /** + * If this is true, then an option-scid-alias channel-type open will be + * attempted. + */ + scidAlias: boolean; + /** The base fee charged regardless of the number of milli-satoshis sent. */ + baseFee: string; + /** + * The fee rate in ppm (parts per million) that will be charged in + * proportion of the value of each forwarded HTLC. + */ + feeRate: string; + /** + * If use_base_fee is true the open channel announcement will update the + * channel base fee with the value specified in base_fee. In the case of + * a base_fee of 0 use_base_fee is needed downstream to distinguish whether + * to use the default base fee value specified in the config or 0. + */ + useBaseFee: boolean; + /** + * If use_fee_rate is true the open channel announcement will update the + * channel fee rate with the value specified in fee_rate. In the case of + * a fee_rate of 0 use_fee_rate is needed downstream to distinguish whether + * to use the default fee rate value specified in the config or 0. + */ + useFeeRate: boolean; + /** + * The number of satoshis we require the remote peer to reserve. This value, + * if specified, must be above the dust limit and below 20% of the channel + * capacity. + */ + remoteChanReserveSat: string; + /** + * If set, then lnd will attempt to commit all the coins under control of the + * internal wallet to open the channel, and the LocalFundingAmount field must + * be zero and is ignored. + */ + fundMax: boolean; + /** + * An optional note-to-self to go along with the channel containing some + * useful information. This is only ever stored locally and in no way impacts + * the channel's operation. + */ + memo: string; + /** A list of selected outpoints that are allocated for channel funding. */ + outpoints: OutPoint[]; +} + +export interface OpenStatusUpdate { + /** + * Signals that the channel is now fully negotiated and the funding + * transaction published. + */ + chanPending: PendingUpdate | undefined; + /** + * Signals that the channel's funding transaction has now reached the + * required number of confirmations on chain and can be used. + */ + chanOpen: ChannelOpenUpdate | undefined; + /** + * Signals that the funding process has been suspended and the construction + * of a PSBT that funds the channel PK script is now required. + */ + psbtFund: ReadyForPsbtFunding | undefined; + /** + * The pending channel ID of the created channel. This value may be used to + * further the funding flow manually via the FundingStateStep method. + */ + pendingChanId: Uint8Array | string; +} + +export interface KeyLocator { + /** The family of key being identified. */ + keyFamily: number; + /** The precise index of the key being identified. */ + keyIndex: number; +} + +export interface KeyDescriptor { + /** The raw bytes of the key being identified. */ + rawKeyBytes: Uint8Array | string; + /** The key locator that identifies which key to use for signing. */ + keyLoc: KeyLocator | undefined; +} + +export interface ChanPointShim { + /** + * The size of the pre-crafted output to be used as the channel point for this + * channel funding. + */ + amt: string; + /** The target channel point to refrence in created commitment transactions. */ + chanPoint: ChannelPoint | undefined; + /** Our local key to use when creating the multi-sig output. */ + localKey: KeyDescriptor | undefined; + /** The key of the remote party to use when creating the multi-sig output. */ + remoteKey: Uint8Array | string; + /** + * If non-zero, then this will be used as the pending channel ID on the wire + * protocol to initate the funding request. This is an optional field, and + * should only be set if the responder is already expecting a specific pending + * channel ID. + */ + pendingChanId: Uint8Array | string; + /** + * This uint32 indicates if this channel is to be considered 'frozen'. A frozen + * channel does not allow a cooperative channel close by the initiator. The + * thaw_height is the height that this restriction stops applying to the + * channel. The height can be interpreted in two ways: as a relative height if + * the value is less than 500,000, or as an absolute height otherwise. + */ + thawHeight: number; + /** Indicates that the funding output is using a MuSig2 multi-sig output. */ + musig2: boolean; +} + +export interface PsbtShim { + /** + * A unique identifier of 32 random bytes that will be used as the pending + * channel ID to identify the PSBT state machine when interacting with it and + * on the wire protocol to initiate the funding request. + */ + pendingChanId: Uint8Array | string; + /** + * An optional base PSBT the new channel output will be added to. If this is + * non-empty, it must be a binary serialized PSBT. + */ + basePsbt: Uint8Array | string; + /** + * If a channel should be part of a batch (multiple channel openings in one + * transaction), it can be dangerous if the whole batch transaction is + * published too early before all channel opening negotiations are completed. + * This flag prevents this particular channel from broadcasting the transaction + * after the negotiation with the remote peer. In a batch of channel openings + * this flag should be set to true for every channel but the very last. + */ + noPublish: boolean; +} + +export interface FundingShim { + /** + * A channel shim where the channel point was fully constructed outside + * of lnd's wallet and the transaction might already be published. + */ + chanPointShim: ChanPointShim | undefined; + /** + * A channel shim that uses a PSBT to fund and sign the channel funding + * transaction. + */ + psbtShim: PsbtShim | undefined; +} + +export interface FundingShimCancel { + /** The pending channel ID of the channel to cancel the funding shim for. */ + pendingChanId: Uint8Array | string; +} + +export interface FundingPsbtVerify { + /** + * The funded but not yet signed PSBT that sends the exact channel capacity + * amount to the PK script returned in the open channel message in a previous + * step. + */ + fundedPsbt: Uint8Array | string; + /** The pending channel ID of the channel to get the PSBT for. */ + pendingChanId: Uint8Array | string; + /** + * Can only be used if the no_publish flag was set to true in the OpenChannel + * call meaning that the caller is solely responsible for publishing the final + * funding transaction. If skip_finalize is set to true then lnd will not wait + * for a FundingPsbtFinalize state step and instead assumes that a transaction + * with the same TXID as the passed in PSBT will eventually confirm. + * IT IS ABSOLUTELY IMPERATIVE that the TXID of the transaction that is + * eventually published does have the _same TXID_ as the verified PSBT. That + * means no inputs or outputs can change, only signatures can be added. If the + * TXID changes between this call and the publish step then the channel will + * never be created and the funds will be in limbo. + */ + skipFinalize: boolean; +} + +export interface FundingPsbtFinalize { + /** + * The funded PSBT that contains all witness data to send the exact channel + * capacity amount to the PK script returned in the open channel message in a + * previous step. Cannot be set at the same time as final_raw_tx. + */ + signedPsbt: Uint8Array | string; + /** The pending channel ID of the channel to get the PSBT for. */ + pendingChanId: Uint8Array | string; + /** + * As an alternative to the signed PSBT with all witness data, the final raw + * wire format transaction can also be specified directly. Cannot be set at the + * same time as signed_psbt. + */ + finalRawTx: Uint8Array | string; +} + +export interface FundingTransitionMsg { + /** + * The funding shim to register. This should be used before any + * channel funding has began by the remote party, as it is intended as a + * preparatory step for the full channel funding. + */ + shimRegister: FundingShim | undefined; + /** Used to cancel an existing registered funding shim. */ + shimCancel: FundingShimCancel | undefined; + /** + * Used to continue a funding flow that was initiated to be executed + * through a PSBT. This step verifies that the PSBT contains the correct + * outputs to fund the channel. + */ + psbtVerify: FundingPsbtVerify | undefined; + /** + * Used to continue a funding flow that was initiated to be executed + * through a PSBT. This step finalizes the funded and signed PSBT, finishes + * negotiation with the peer and finally publishes the resulting funding + * transaction. + */ + psbtFinalize: FundingPsbtFinalize | undefined; +} + +export interface FundingStateStepResp {} + +export interface PendingHTLC { + /** The direction within the channel that the htlc was sent */ + incoming: boolean; + /** The total value of the htlc */ + amount: string; + /** The final output to be swept back to the user's wallet */ + outpoint: string; + /** The next block height at which we can spend the current stage */ + maturityHeight: number; + /** + * The number of blocks remaining until the current stage can be swept. + * Negative values indicate how many blocks have passed since becoming + * mature. + */ + blocksTilMaturity: number; + /** Indicates whether the htlc is in its first or second stage of recovery */ + stage: number; +} + +export interface PendingChannelsRequest { + /** + * Indicates whether to include the raw transaction hex for + * waiting_close_channels. + */ + includeRawTx: boolean; +} + +export interface PendingChannelsResponse { + /** The balance in satoshis encumbered in pending channels */ + totalLimboBalance: string; + /** Channels pending opening */ + pendingOpenChannels: PendingChannelsResponse_PendingOpenChannel[]; + /** + * Deprecated: Channels pending closing previously contained cooperatively + * closed channels with a single confirmation. These channels are now + * considered closed from the time we see them on chain. + * + * @deprecated + */ + pendingClosingChannels: PendingChannelsResponse_ClosedChannel[]; + /** Channels pending force closing */ + pendingForceClosingChannels: PendingChannelsResponse_ForceClosedChannel[]; + /** Channels waiting for closing tx to confirm */ + waitingCloseChannels: PendingChannelsResponse_WaitingCloseChannel[]; +} + +export interface PendingChannelsResponse_PendingChannel { + remoteNodePub: string; + channelPoint: string; + capacity: string; + localBalance: string; + remoteBalance: string; + /** + * The minimum satoshis this node is required to reserve in its + * balance. + */ + localChanReserveSat: string; + /** + * The minimum satoshis the other node is required to reserve in its + * balance. + */ + remoteChanReserveSat: string; + /** The party that initiated opening the channel. */ + initiator: Initiator; + /** The commitment type used by this channel. */ + commitmentType: CommitmentType; + /** Total number of forwarding packages created in this channel. */ + numForwardingPackages: string; + /** A set of flags showing the current state of the channel. */ + chanStatusFlags: string; + /** Whether this channel is advertised to the network or not. */ + private: boolean; + /** + * An optional note-to-self to go along with the channel containing some + * useful information. This is only ever stored locally and in no way + * impacts the channel's operation. + */ + memo: string; + /** Custom channel data that might be populated in custom channels. */ + customChannelData: Uint8Array | string; +} + +export interface PendingChannelsResponse_PendingOpenChannel { + /** The pending channel */ + channel: PendingChannelsResponse_PendingChannel | undefined; + /** + * The amount calculated to be paid in fees for the current set of + * commitment transactions. The fee amount is persisted with the channel + * in order to allow the fee amount to be removed and recalculated with + * each channel state update, including updates that happen after a system + * restart. + */ + commitFee: string; + /** The weight of the commitment transaction */ + commitWeight: string; + /** + * The required number of satoshis per kilo-weight that the requester will + * pay at all times, for both the funding transaction and commitment + * transaction. This value can later be updated once the channel is open. + */ + feePerKw: string; + /** + * The number of blocks until the funding transaction is considered + * expired. If this value gets close to zero, there is a risk that the + * channel funding will be canceled by the channel responder. The + * channel should be fee bumped using CPFP (see walletrpc.BumpFee) to + * ensure that the channel confirms in time. Otherwise a force-close + * will be necessary if the channel confirms after the funding + * transaction expires. A negative value means the channel responder has + * very likely canceled the funding and the channel will never become + * fully operational. + */ + fundingExpiryBlocks: number; +} + +export interface PendingChannelsResponse_WaitingCloseChannel { + /** The pending channel waiting for closing tx to confirm */ + channel: PendingChannelsResponse_PendingChannel | undefined; + /** The balance in satoshis encumbered in this channel */ + limboBalance: string; + /** + * A list of valid commitment transactions. Any of these can confirm at + * this point. + */ + commitments: PendingChannelsResponse_Commitments | undefined; + /** The transaction id of the closing transaction */ + closingTxid: string; + /** + * The raw hex encoded bytes of the closing transaction. Included if + * include_raw_tx in the request is true. + */ + closingTxHex: string; +} + +export interface PendingChannelsResponse_Commitments { + /** Hash of the local version of the commitment tx. */ + localTxid: string; + /** Hash of the remote version of the commitment tx. */ + remoteTxid: string; + /** Hash of the remote pending version of the commitment tx. */ + remotePendingTxid: string; + /** + * The amount in satoshis calculated to be paid in fees for the local + * commitment. + */ + localCommitFeeSat: string; + /** + * The amount in satoshis calculated to be paid in fees for the remote + * commitment. + */ + remoteCommitFeeSat: string; + /** + * The amount in satoshis calculated to be paid in fees for the remote + * pending commitment. + */ + remotePendingCommitFeeSat: string; +} + +export interface PendingChannelsResponse_ClosedChannel { + /** The pending channel to be closed */ + channel: PendingChannelsResponse_PendingChannel | undefined; + /** The transaction id of the closing transaction */ + closingTxid: string; +} + +export interface PendingChannelsResponse_ForceClosedChannel { + /** The pending channel to be force closed */ + channel: PendingChannelsResponse_PendingChannel | undefined; + /** The transaction id of the closing transaction */ + closingTxid: string; + /** The balance in satoshis encumbered in this pending channel */ + limboBalance: string; + /** The height at which funds can be swept into the wallet */ + maturityHeight: number; + /** + * Remaining # of blocks until the commitment output can be swept. + * Negative values indicate how many blocks have passed since becoming + * mature. + */ + blocksTilMaturity: number; + /** The total value of funds successfully recovered from this channel */ + recoveredBalance: string; + pendingHtlcs: PendingHTLC[]; + anchor: PendingChannelsResponse_ForceClosedChannel_AnchorState; +} + +/** + * There are three resolution states for the anchor: + * limbo, lost and recovered. Derive the current state + * from the limbo and recovered balances. + */ +export enum PendingChannelsResponse_ForceClosedChannel_AnchorState { + /** LIMBO - The recovered_balance is zero and limbo_balance is non-zero. */ + LIMBO = 'LIMBO', + /** RECOVERED - The recovered_balance is non-zero. */ + RECOVERED = 'RECOVERED', + /** LOST - A state that is neither LIMBO nor RECOVERED. */ + LOST = 'LOST', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export interface ChannelEventSubscription {} + +export interface ChannelEventUpdate { + openChannel: Channel | undefined; + closedChannel: ChannelCloseSummary | undefined; + activeChannel: ChannelPoint | undefined; + inactiveChannel: ChannelPoint | undefined; + pendingOpenChannel: PendingUpdate | undefined; + fullyResolvedChannel: ChannelPoint | undefined; + type: ChannelEventUpdate_UpdateType; +} + +export enum ChannelEventUpdate_UpdateType { + OPEN_CHANNEL = 'OPEN_CHANNEL', + CLOSED_CHANNEL = 'CLOSED_CHANNEL', + ACTIVE_CHANNEL = 'ACTIVE_CHANNEL', + INACTIVE_CHANNEL = 'INACTIVE_CHANNEL', + PENDING_OPEN_CHANNEL = 'PENDING_OPEN_CHANNEL', + FULLY_RESOLVED_CHANNEL = 'FULLY_RESOLVED_CHANNEL', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export interface WalletAccountBalance { + /** The confirmed balance of the account (with >= 1 confirmations). */ + confirmedBalance: string; + /** The unconfirmed balance of the account (with 0 confirmations). */ + unconfirmedBalance: string; +} + +export interface WalletBalanceRequest { + /** + * The wallet account the balance is shown for. + * If this is not specified, the balance of the "default" account is shown. + */ + account: string; + /** + * The minimum number of confirmations each one of your outputs used for the + * funding transaction must satisfy. If this is not specified, the default + * value of 1 is used. + */ + minConfs: number; +} + +export interface WalletBalanceResponse { + /** The balance of the wallet */ + totalBalance: string; + /** The confirmed balance of a wallet(with >= 1 confirmations) */ + confirmedBalance: string; + /** The unconfirmed balance of a wallet(with 0 confirmations) */ + unconfirmedBalance: string; + /** + * The total amount of wallet UTXOs held in outputs that are locked for + * other usage. + */ + lockedBalance: string; + /** The amount of reserve required. */ + reservedBalanceAnchorChan: string; + /** A mapping of each wallet account's name to its balance. */ + accountBalance: { [key: string]: WalletAccountBalance }; +} + +export interface WalletBalanceResponse_AccountBalanceEntry { + key: string; + value: WalletAccountBalance | undefined; +} + +export interface Amount { + /** Value denominated in satoshis. */ + sat: string; + /** Value denominated in milli-satoshis. */ + msat: string; +} + +export interface ChannelBalanceRequest {} + +export interface ChannelBalanceResponse { + /** + * Deprecated. Sum of channels balances denominated in satoshis + * + * @deprecated + */ + balance: string; + /** + * Deprecated. Sum of channels pending balances denominated in satoshis + * + * @deprecated + */ + pendingOpenBalance: string; + /** Sum of channels local balances. */ + localBalance: Amount | undefined; + /** Sum of channels remote balances. */ + remoteBalance: Amount | undefined; + /** Sum of channels local unsettled balances. */ + unsettledLocalBalance: Amount | undefined; + /** Sum of channels remote unsettled balances. */ + unsettledRemoteBalance: Amount | undefined; + /** Sum of channels pending local balances. */ + pendingOpenLocalBalance: Amount | undefined; + /** Sum of channels pending remote balances. */ + pendingOpenRemoteBalance: Amount | undefined; + /** + * Custom channel data that might be populated if there are custom channels + * present. + */ + customChannelData: Uint8Array | string; +} + +export interface QueryRoutesRequest { + /** The 33-byte hex-encoded public key for the payment destination */ + pubKey: string; + /** + * The amount to send expressed in satoshis. + * + * The fields amt and amt_msat are mutually exclusive. + */ + amt: string; + /** + * The amount to send expressed in millisatoshis. + * + * The fields amt and amt_msat are mutually exclusive. + */ + amtMsat: string; + /** + * An optional CLTV delta from the current height that should be used for the + * timelock of the final hop. Note that unlike SendPayment, QueryRoutes does + * not add any additional block padding on top of final_ctlv_delta. This + * padding of a few blocks needs to be added manually or otherwise failures may + * happen when a block comes in while the payment is in flight. + * + * Note: must not be set if making a payment to a blinded path (delta is + * set by the aggregate parameters provided by blinded_payment_paths) + */ + finalCltvDelta: number; + /** + * The maximum number of satoshis that will be paid as a fee of the payment. + * This value can be represented either as a percentage of the amount being + * sent, or as a fixed amount of the maximum fee the user is willing the pay to + * send the payment. If not specified, lnd will use a default value of 100% + * fees for small amounts (<=1k sat) or 5% fees for larger amounts. + */ + feeLimit: FeeLimit | undefined; + /** + * A list of nodes to ignore during path finding. When using REST, these fields + * must be encoded as base64. + */ + ignoredNodes: Uint8Array | string[]; + /** + * Deprecated. A list of edges to ignore during path finding. + * + * @deprecated + */ + ignoredEdges: EdgeLocator[]; + /** + * The source node where the request route should originated from. If empty, + * self is assumed. + */ + sourcePubKey: string; + /** + * If set to true, edge probabilities from mission control will be used to get + * the optimal route. + */ + useMissionControl: boolean; + /** A list of directed node pairs that will be ignored during path finding. */ + ignoredPairs: NodePair[]; + /** + * An optional maximum total time lock for the route. If the source is empty or + * ourselves, this should not exceed lnd's `--max-cltv-expiry` setting. If + * zero, then the value of `--max-cltv-expiry` is used as the limit. + */ + cltvLimit: number; + /** + * An optional field that can be used to pass an arbitrary set of TLV records + * to a peer which understands the new records. This can be used to pass + * application specific data during the payment attempt. If the destination + * does not support the specified records, an error will be returned. + * Record types are required to be in the custom range >= 65536. When using + * REST, the values must be encoded as base64. + */ + destCustomRecords: { [key: string]: Uint8Array | string }; + /** + * The channel id of the channel that must be taken to the first hop. If zero, + * any channel may be used. + */ + outgoingChanId: string; + /** The pubkey of the last hop of the route. If empty, any hop may be used. */ + lastHopPubkey: Uint8Array | string; + /** Optional route hints to reach the destination through private channels. */ + routeHints: RouteHint[]; + /** + * An optional blinded path(s) to reach the destination. Note that the + * introduction node must be provided as the first hop in the route. + */ + blindedPaymentPaths: BlindedPaymentPath[]; + /** + * Features assumed to be supported by the final node. All transitive feature + * dependencies must also be set properly. For a given feature bit pair, either + * optional or remote may be set, but not both. If this field is nil or empty, + * the router will try to load destination features from the graph as a + * fallback. + * + * Note: must not be set if making a payment to a blinded route (features + * are provided in blinded_payment_paths). + */ + destFeatures: FeatureBit[]; + /** + * The time preference for this payment. Set to -1 to optimize for fees + * only, to 1 to optimize for reliability only or a value inbetween for a mix. + */ + timePref: number; +} + +export interface QueryRoutesRequest_DestCustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + +export interface NodePair { + /** + * The sending node of the pair. When using REST, this field must be encoded as + * base64. + */ + from: Uint8Array | string; + /** + * The receiving node of the pair. When using REST, this field must be encoded + * as base64. + */ + to: Uint8Array | string; +} + +export interface EdgeLocator { + /** The short channel id of this edge. */ + channelId: string; + /** + * The direction of this edge. If direction_reverse is false, the direction + * of this edge is from the channel endpoint with the lexicographically smaller + * pub key to the endpoint with the larger pub key. If direction_reverse is + * is true, the edge goes the other way. + */ + directionReverse: boolean; +} + +export interface QueryRoutesResponse { + /** + * The route that results from the path finding operation. This is still a + * repeated field to retain backwards compatibility. + */ + routes: Route[]; + /** + * The success probability of the returned route based on the current mission + * control state. [EXPERIMENTAL] + */ + successProb: number; +} + +export interface Hop { + /** + * The unique channel ID for the channel. The first 3 bytes are the block + * height, the next 3 the index within the block, and the last 2 bytes are the + * output index for the channel. + */ + chanId: string; + /** @deprecated */ + chanCapacity: string; + /** @deprecated */ + amtToForward: string; + /** @deprecated */ + fee: string; + expiry: number; + amtToForwardMsat: string; + feeMsat: string; + /** + * An optional public key of the hop. If the public key is given, the payment + * can be executed without relying on a copy of the channel graph. + */ + pubKey: string; + /** + * If set to true, then this hop will be encoded using the new variable length + * TLV format. Note that if any custom tlv_records below are specified, then + * this field MUST be set to true for them to be encoded properly. + * + * @deprecated + */ + tlvPayload: boolean; + /** + * An optional TLV record that signals the use of an MPP payment. If present, + * the receiver will enforce that the same mpp_record is included in the final + * hop payload of all non-zero payments in the HTLC set. If empty, a regular + * single-shot payment is or was attempted. + */ + mppRecord: MPPRecord | undefined; + /** + * An optional TLV record that signals the use of an AMP payment. If present, + * the receiver will treat all received payments including the same + * (payment_addr, set_id) pair as being part of one logical payment. The + * payment will be settled by XORing the root_share's together and deriving the + * child hashes and preimages according to BOLT XX. Must be used in conjunction + * with mpp_record. + */ + ampRecord: AMPRecord | undefined; + /** + * An optional set of key-value TLV records. This is useful within the context + * of the SendToRoute call as it allows callers to specify arbitrary K-V pairs + * to drop off at each hop within the onion. + */ + customRecords: { [key: string]: Uint8Array | string }; + /** The payment metadata to send along with the payment to the payee. */ + metadata: Uint8Array | string; + /** + * Blinding point is an optional blinding point included for introduction + * nodes in blinded paths. This field is mandatory for hops that represents + * the introduction point in a blinded path. + */ + blindingPoint: Uint8Array | string; + /** + * Encrypted data is a receiver-produced blob of data that provides hops + * in a blinded route with forwarding data. As this data is encrypted by + * the recipient, we will not be able to parse it - it is essentially an + * arbitrary blob of data from our node's perspective. This field is + * mandatory for all hops in a blinded path, including the introduction + * node. + */ + encryptedData: Uint8Array | string; + /** + * The total amount that is sent to the recipient (possibly across multiple + * HTLCs), as specified by the sender when making a payment to a blinded path. + * This value is only set in the final hop payload of a blinded payment. This + * value is analogous to the MPPRecord that is used for regular (non-blinded) + * MPP payments. + */ + totalAmtMsat: string; +} + +export interface Hop_CustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + +export interface MPPRecord { + /** + * A unique, random identifier used to authenticate the sender as the intended + * payer of a multi-path payment. The payment_addr must be the same for all + * subpayments, and match the payment_addr provided in the receiver's invoice. + * The same payment_addr must be used on all subpayments. This is also called + * payment secret in specifications (e.g. BOLT 11). + */ + paymentAddr: Uint8Array | string; + /** + * The total amount in milli-satoshis being sent as part of a larger multi-path + * payment. The caller is responsible for ensuring subpayments to the same node + * and payment_hash sum exactly to total_amt_msat. The same + * total_amt_msat must be used on all subpayments. + */ + totalAmtMsat: string; +} + +export interface AMPRecord { + rootShare: Uint8Array | string; + setId: Uint8Array | string; + childIndex: number; +} + +/** + * A path through the channel graph which runs over one or more channels in + * succession. This struct carries all the information required to craft the + * Sphinx onion packet, and send the payment along the first hop in the path. A + * route is only selected as valid if all the channels have sufficient capacity to + * carry the initial payment amount after fees are accounted for. + */ +export interface Route { + /** + * The cumulative (final) time lock across the entire route. This is the CLTV + * value that should be extended to the first hop in the route. All other hops + * will decrement the time-lock as advertised, leaving enough time for all + * hops to wait for or present the payment preimage to complete the payment. + */ + totalTimeLock: number; + /** + * The sum of the fees paid at each hop within the final route. In the case + * of a one-hop payment, this value will be zero as we don't need to pay a fee + * to ourselves. + * + * @deprecated + */ + totalFees: string; + /** + * The total amount of funds required to complete a payment over this route. + * This value includes the cumulative fees at each hop. As a result, the HTLC + * extended to the first-hop in the route will need to have at least this many + * satoshis, otherwise the route will fail at an intermediate node due to an + * insufficient amount of fees. + * + * @deprecated + */ + totalAmt: string; + /** Contains details concerning the specific forwarding details at each hop. */ + hops: Hop[]; + /** The total fees in millisatoshis. */ + totalFeesMsat: string; + /** The total amount in millisatoshis. */ + totalAmtMsat: string; + /** + * The actual on-chain amount that was sent out to the first hop. This value is + * only different from the total_amt_msat field if this is a custom channel + * payment and the value transported in the HTLC is different from the BTC + * amount in the HTLC. If this value is zero, then this is an old payment that + * didn't have this value yet and can be ignored. + */ + firstHopAmountMsat: string; + /** Custom channel data that might be populated in custom channels. */ + customChannelData: Uint8Array | string; +} + +export interface NodeInfoRequest { + /** The 33-byte hex-encoded compressed public of the target node */ + pubKey: string; + /** If true, will include all known channels associated with the node. */ + includeChannels: boolean; +} + +export interface NodeInfo { + /** + * An individual vertex/node within the channel graph. A node is + * connected to other nodes by one or more channel edges emanating from it. As + * the graph is directed, a node will also have an incoming edge attached to + * it for each outgoing edge. + */ + node: LightningNode | undefined; + /** The total number of channels for the node. */ + numChannels: number; + /** The sum of all channels capacity for the node, denominated in satoshis. */ + totalCapacity: string; + /** A list of all public channels for the node. */ + channels: ChannelEdge[]; +} + +/** + * An individual vertex/node within the channel graph. A node is + * connected to other nodes by one or more channel edges emanating from it. As the + * graph is directed, a node will also have an incoming edge attached to it for + * each outgoing edge. + */ +export interface LightningNode { + lastUpdate: number; + pubKey: string; + alias: string; + addresses: NodeAddress[]; + color: string; + features: { [key: number]: Feature }; + /** Custom node announcement tlv records. */ + customRecords: { [key: string]: Uint8Array | string }; +} + +export interface LightningNode_FeaturesEntry { + key: number; + value: Feature | undefined; +} + +export interface LightningNode_CustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + +export interface NodeAddress { + network: string; + addr: string; +} + +export interface RoutingPolicy { + timeLockDelta: number; + minHtlc: string; + feeBaseMsat: string; + feeRateMilliMsat: string; + disabled: boolean; + maxHtlcMsat: string; + lastUpdate: number; + /** Custom channel update tlv records. */ + customRecords: { [key: string]: Uint8Array | string }; + inboundFeeBaseMsat: number; + inboundFeeRateMilliMsat: number; +} + +export interface RoutingPolicy_CustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + +/** + * A fully authenticated channel along with all its unique attributes. + * Once an authenticated channel announcement has been processed on the network, + * then an instance of ChannelEdgeInfo encapsulating the channels attributes is + * stored. The other portions relevant to routing policy of a channel are stored + * within a ChannelEdgePolicy for each direction of the channel. + */ +export interface ChannelEdge { + /** + * The unique channel ID for the channel. The first 3 bytes are the block + * height, the next 3 the index within the block, and the last 2 bytes are the + * output index for the channel. + */ + channelId: string; + chanPoint: string; + /** @deprecated */ + lastUpdate: number; + node1Pub: string; + node2Pub: string; + capacity: string; + node1Policy: RoutingPolicy | undefined; + node2Policy: RoutingPolicy | undefined; + /** Custom channel announcement tlv records. */ + customRecords: { [key: string]: Uint8Array | string }; +} + +export interface ChannelEdge_CustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + +export interface ChannelGraphRequest { + /** + * Whether unannounced channels are included in the response or not. If set, + * unannounced channels are included. Unannounced channels are both private + * channels, and public channels that are not yet announced to the network. + */ + includeUnannounced: boolean; +} + +/** Returns a new instance of the directed channel graph. */ +export interface ChannelGraph { + /** The list of `LightningNode`s in this channel graph */ + nodes: LightningNode[]; + /** The list of `ChannelEdge`s in this channel graph */ + edges: ChannelEdge[]; +} + +export interface NodeMetricsRequest { + /** The requested node metrics. */ + types: NodeMetricType[]; +} + +export interface NodeMetricsResponse { + /** + * Betweenness centrality is the sum of the ratio of shortest paths that pass + * through the node for each pair of nodes in the graph (not counting paths + * starting or ending at this node). + * Map of node pubkey to betweenness centrality of the node. Normalized + * values are in the [0,1] closed interval. + */ + betweennessCentrality: { [key: string]: FloatMetric }; +} + +export interface NodeMetricsResponse_BetweennessCentralityEntry { + key: string; + value: FloatMetric | undefined; +} + +export interface FloatMetric { + /** Arbitrary float value. */ + value: number; + /** The value normalized to [0,1] or [-1,1]. */ + normalizedValue: number; +} + +export interface ChanInfoRequest { + /** + * The unique channel ID for the channel. The first 3 bytes are the block + * height, the next 3 the index within the block, and the last 2 bytes are the + * output index for the channel. + */ + chanId: string; + /** + * The channel point of the channel in format funding_txid:output_index. If + * chan_id is specified, this field is ignored. + */ + chanPoint: string; +} + +export interface NetworkInfoRequest {} + +export interface NetworkInfo { + graphDiameter: number; + avgOutDegree: number; + maxOutDegree: number; + numNodes: number; + numChannels: number; + totalNetworkCapacity: string; + avgChannelSize: number; + minChannelSize: string; + maxChannelSize: string; + medianChannelSizeSat: string; + /** The number of edges marked as zombies. */ + numZombieChans: string; +} + +export interface StopRequest {} + +export interface StopResponse {} + +export interface GraphTopologySubscription {} + +export interface GraphTopologyUpdate { + nodeUpdates: NodeUpdate[]; + channelUpdates: ChannelEdgeUpdate[]; + closedChans: ClosedChannelUpdate[]; +} + +export interface NodeUpdate { + /** + * Deprecated, use node_addresses. + * + * @deprecated + */ + addresses: string[]; + identityKey: string; + /** + * Deprecated, use features. + * + * @deprecated + */ + globalFeatures: Uint8Array | string; + alias: string; + color: string; + nodeAddresses: NodeAddress[]; + /** + * Features that the node has advertised in the init message, node + * announcements and invoices. + */ + features: { [key: number]: Feature }; +} + +export interface NodeUpdate_FeaturesEntry { + key: number; + value: Feature | undefined; +} + +export interface ChannelEdgeUpdate { + /** + * The unique channel ID for the channel. The first 3 bytes are the block + * height, the next 3 the index within the block, and the last 2 bytes are the + * output index for the channel. + */ + chanId: string; + chanPoint: ChannelPoint | undefined; + capacity: string; + routingPolicy: RoutingPolicy | undefined; + advertisingNode: string; + connectingNode: string; +} + +export interface ClosedChannelUpdate { + /** + * The unique channel ID for the channel. The first 3 bytes are the block + * height, the next 3 the index within the block, and the last 2 bytes are the + * output index for the channel. + */ + chanId: string; + capacity: string; + closedHeight: number; + chanPoint: ChannelPoint | undefined; +} + +export interface HopHint { + /** The public key of the node at the start of the channel. */ + nodeId: string; + /** The unique identifier of the channel. */ + chanId: string; + /** The base fee of the channel denominated in millisatoshis. */ + feeBaseMsat: number; + /** + * The fee rate of the channel for sending one satoshi across it denominated in + * millionths of a satoshi. + */ + feeProportionalMillionths: number; + /** The time-lock delta of the channel. */ + cltvExpiryDelta: number; +} + +export interface SetID { + setId: Uint8Array | string; +} + +export interface RouteHint { + /** + * A list of hop hints that when chained together can assist in reaching a + * specific destination. + */ + hopHints: HopHint[]; +} + +export interface BlindedPaymentPath { + /** The blinded path to send the payment to. */ + blindedPath: BlindedPath | undefined; + /** The base fee for the blinded path provided, expressed in msat. */ + baseFeeMsat: string; + /** + * The proportional fee for the blinded path provided, expressed in parts + * per million. + */ + proportionalFeeRate: number; + /** + * The total CLTV delta for the blinded path provided, including the + * final CLTV delta for the receiving node. + */ + totalCltvDelta: number; + /** + * The minimum hltc size that may be sent over the blinded path, expressed + * in msat. + */ + htlcMinMsat: string; + /** + * The maximum htlc size that may be sent over the blinded path, expressed + * in msat. + */ + htlcMaxMsat: string; + /** The feature bits for the route. */ + features: FeatureBit[]; +} + +export interface BlindedPath { + /** The unblinded pubkey of the introduction node for the route. */ + introductionNode: Uint8Array | string; + /** The ephemeral pubkey used by nodes in the blinded route. */ + blindingPoint: Uint8Array | string; + /** + * A set of blinded node keys and data blobs for the blinded portion of the + * route. Note that the first hop is expected to be the introduction node, + * so the route is always expected to have at least one hop. + */ + blindedHops: BlindedHop[]; +} + +export interface BlindedHop { + /** The blinded public key of the node. */ + blindedNode: Uint8Array | string; + /** An encrypted blob of data provided to the blinded node. */ + encryptedData: Uint8Array | string; +} + +export interface AMPInvoiceState { + /** The state the HTLCs associated with this setID are in. */ + state: InvoiceHTLCState; + /** The settle index of this HTLC set, if the invoice state is settled. */ + settleIndex: string; + /** The time this HTLC set was settled expressed in unix epoch. */ + settleTime: string; + /** The total amount paid for the sub-invoice expressed in milli satoshis. */ + amtPaidMsat: string; +} + +export interface Invoice { + /** + * An optional memo to attach along with the invoice. Used for record keeping + * purposes for the invoice's creator, and will also be set in the description + * field of the encoded payment request if the description_hash field is not + * being used. + */ + memo: string; + /** + * The hex-encoded preimage (32 byte) which will allow settling an incoming + * HTLC payable to this preimage. When using REST, this field must be encoded + * as base64. + */ + rPreimage: Uint8Array | string; + /** + * The hash of the preimage. When using REST, this field must be encoded as + * base64. + * Note: Output only, don't specify for creating an invoice. + */ + rHash: Uint8Array | string; + /** + * The value of this invoice in satoshis + * + * The fields value and value_msat are mutually exclusive. + */ + value: string; + /** + * The value of this invoice in millisatoshis + * + * The fields value and value_msat are mutually exclusive. + */ + valueMsat: string; + /** + * Whether this invoice has been fulfilled. + * + * The field is deprecated. Use the state field instead (compare to SETTLED). + * + * @deprecated + */ + settled: boolean; + /** + * When this invoice was created. + * Measured in seconds since the unix epoch. + * Note: Output only, don't specify for creating an invoice. + */ + creationDate: string; + /** + * When this invoice was settled. + * Measured in seconds since the unix epoch. + * Note: Output only, don't specify for creating an invoice. + */ + settleDate: string; + /** + * A bare-bones invoice for a payment within the Lightning Network. With the + * details of the invoice, the sender has all the data necessary to send a + * payment to the recipient. + * Note: Output only, don't specify for creating an invoice. + */ + paymentRequest: string; + /** + * Hash (SHA-256) of a description of the payment. Used if the description of + * payment (memo) is too long to naturally fit within the description field + * of an encoded payment request. When using REST, this field must be encoded + * as base64. + */ + descriptionHash: Uint8Array | string; + /** Payment request expiry time in seconds. Default is 86400 (24 hours). */ + expiry: string; + /** Fallback on-chain address. */ + fallbackAddr: string; + /** Delta to use for the time-lock of the CLTV extended to the final hop. */ + cltvExpiry: string; + /** + * Route hints that can each be individually used to assist in reaching the + * invoice's destination. + */ + routeHints: RouteHint[]; + /** + * Whether this invoice should include routing hints for private channels. + * Note: When enabled, if value and value_msat are zero, a large number of + * hints with these channels can be included, which might not be desirable. + */ + private: boolean; + /** + * The "add" index of this invoice. Each newly created invoice will increment + * this index making it monotonically increasing. Callers to the + * SubscribeInvoices call can use this to instantly get notified of all added + * invoices with an add_index greater than this one. + * Note: Output only, don't specify for creating an invoice. + */ + addIndex: string; + /** + * The "settle" index of this invoice. Each newly settled invoice will + * increment this index making it monotonically increasing. Callers to the + * SubscribeInvoices call can use this to instantly get notified of all + * settled invoices with an settle_index greater than this one. + * Note: Output only, don't specify for creating an invoice. + */ + settleIndex: string; + /** + * Deprecated, use amt_paid_sat or amt_paid_msat. + * + * @deprecated + */ + amtPaid: string; + /** + * The amount that was accepted for this invoice, in satoshis. This will ONLY + * be set if this invoice has been settled or accepted. We provide this field + * as if the invoice was created with a zero value, then we need to record what + * amount was ultimately accepted. Additionally, it's possible that the sender + * paid MORE that was specified in the original invoice. So we'll record that + * here as well. + * Note: Output only, don't specify for creating an invoice. + */ + amtPaidSat: string; + /** + * The amount that was accepted for this invoice, in millisatoshis. This will + * ONLY be set if this invoice has been settled or accepted. We provide this + * field as if the invoice was created with a zero value, then we need to + * record what amount was ultimately accepted. Additionally, it's possible that + * the sender paid MORE that was specified in the original invoice. So we'll + * record that here as well. + * Note: Output only, don't specify for creating an invoice. + */ + amtPaidMsat: string; + /** + * The state the invoice is in. + * Note: Output only, don't specify for creating an invoice. + */ + state: Invoice_InvoiceState; + /** + * List of HTLCs paying to this invoice [EXPERIMENTAL]. + * Note: Output only, don't specify for creating an invoice. + */ + htlcs: InvoiceHTLC[]; + /** + * List of features advertised on the invoice. + * Note: Output only, don't specify for creating an invoice. + */ + features: { [key: number]: Feature }; + /** + * Indicates if this invoice was a spontaneous payment that arrived via keysend + * [EXPERIMENTAL]. + * Note: Output only, don't specify for creating an invoice. + */ + isKeysend: boolean; + /** + * The payment address of this invoice. This is also called payment secret in + * specifications (e.g. BOLT 11). This value will be used in MPP payments, and + * also for newer invoices that always require the MPP payload for added + * end-to-end security. + * Note: Output only, don't specify for creating an invoice. + */ + paymentAddr: Uint8Array | string; + /** Signals whether or not this is an AMP invoice. */ + isAmp: boolean; + /** + * [EXPERIMENTAL]: + * + * Maps a 32-byte hex-encoded set ID to the sub-invoice AMP state for the + * given set ID. This field is always populated for AMP invoices, and can be + * used along side LookupInvoice to obtain the HTLC information related to a + * given sub-invoice. + * Note: Output only, don't specify for creating an invoice. + */ + ampInvoiceState: { [key: string]: AMPInvoiceState }; + /** + * Signals that the invoice should include blinded paths to hide the true + * identity of the recipient. + */ + isBlinded: boolean; + /** + * Config values to use when creating blinded paths for this invoice. These + * can be used to override the defaults config values provided in by the + * global config. This field is only used if is_blinded is true. + */ + blindedPathConfig: BlindedPathConfig | undefined; +} + +export enum Invoice_InvoiceState { + OPEN = 'OPEN', + SETTLED = 'SETTLED', + CANCELED = 'CANCELED', + ACCEPTED = 'ACCEPTED', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export interface Invoice_FeaturesEntry { + key: number; + value: Feature | undefined; +} + +export interface Invoice_AmpInvoiceStateEntry { + key: string; + value: AMPInvoiceState | undefined; +} + +export interface BlindedPathConfig { + /** + * The minimum number of real hops to include in a blinded path. This doesn't + * include our node, so if the minimum is 1, then the path will contain at + * minimum our node along with an introduction node hop. If it is zero then + * the shortest path will use our node as an introduction node. + */ + minNumRealHops?: number | undefined; + /** + * The number of hops to include in a blinded path. This doesn't include our + * node, so if it is 1, then the path will contain our node along with an + * introduction node or dummy node hop. If paths shorter than NumHops is + * found, then they will be padded using dummy hops. + */ + numHops?: number | undefined; + /** The maximum number of blinded paths to select and add to an invoice. */ + maxNumPaths?: number | undefined; + /** + * A list of node IDs of nodes that should not be used in any of our generated + * blinded paths. + */ + nodeOmissionList: Uint8Array | string[]; +} + +/** Details of an HTLC that paid to an invoice */ +export interface InvoiceHTLC { + /** Short channel id over which the htlc was received. */ + chanId: string; + /** Index identifying the htlc on the channel. */ + htlcIndex: string; + /** The amount of the htlc in msat. */ + amtMsat: string; + /** Block height at which this htlc was accepted. */ + acceptHeight: number; + /** Time at which this htlc was accepted. */ + acceptTime: string; + /** Time at which this htlc was settled or canceled. */ + resolveTime: string; + /** Block height at which this htlc expires. */ + expiryHeight: number; + /** Current state the htlc is in. */ + state: InvoiceHTLCState; + /** Custom tlv records. */ + customRecords: { [key: string]: Uint8Array | string }; + /** The total amount of the mpp payment in msat. */ + mppTotalAmtMsat: string; + /** Details relevant to AMP HTLCs, only populated if this is an AMP HTLC. */ + amp: AMP | undefined; + /** Custom channel data that might be populated in custom channels. */ + customChannelData: Uint8Array | string; +} + +export interface InvoiceHTLC_CustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + +/** Details specific to AMP HTLCs. */ +export interface AMP { + /** + * An n-of-n secret share of the root seed from which child payment hashes + * and preimages are derived. + */ + rootShare: Uint8Array | string; + /** An identifier for the HTLC set that this HTLC belongs to. */ + setId: Uint8Array | string; + /** + * A nonce used to randomize the child preimage and child hash from a given + * root_share. + */ + childIndex: number; + /** The payment hash of the AMP HTLC. */ + hash: Uint8Array | string; + /** + * The preimage used to settle this AMP htlc. This field will only be + * populated if the invoice is in InvoiceState_ACCEPTED or + * InvoiceState_SETTLED. + */ + preimage: Uint8Array | string; +} + +export interface AddInvoiceResponse { + rHash: Uint8Array | string; + /** + * A bare-bones invoice for a payment within the Lightning Network. With the + * details of the invoice, the sender has all the data necessary to send a + * payment to the recipient. + */ + paymentRequest: string; + /** + * The "add" index of this invoice. Each newly created invoice will increment + * this index making it monotonically increasing. Callers to the + * SubscribeInvoices call can use this to instantly get notified of all added + * invoices with an add_index greater than this one. + */ + addIndex: string; + /** + * The payment address of the generated invoice. This is also called + * payment secret in specifications (e.g. BOLT 11). This value should be used + * in all payments for this invoice as we require it for end to end security. + */ + paymentAddr: Uint8Array | string; +} + +export interface PaymentHash { + /** + * The hex-encoded payment hash of the invoice to be looked up. The passed + * payment hash must be exactly 32 bytes, otherwise an error is returned. + * Deprecated now that the REST gateway supports base64 encoding of bytes + * fields. + * + * @deprecated + */ + rHashStr: string; + /** + * The payment hash of the invoice to be looked up. When using REST, this field + * must be encoded as base64. + */ + rHash: Uint8Array | string; +} + +export interface ListInvoiceRequest { + /** + * If set, only invoices that are not settled and not canceled will be returned + * in the response. + */ + pendingOnly: boolean; + /** + * The index of an invoice that will be used as either the start or end of a + * query to determine which invoices should be returned in the response. + */ + indexOffset: string; + /** The max number of invoices to return in the response to this query. */ + numMaxInvoices: string; + /** + * If set, the invoices returned will result from seeking backwards from the + * specified index offset. This can be used to paginate backwards. + */ + reversed: boolean; + /** + * If set, returns all invoices with a creation date greater than or equal + * to it. Measured in seconds since the unix epoch. + */ + creationDateStart: string; + /** + * If set, returns all invoices with a creation date less than or equal to + * it. Measured in seconds since the unix epoch. + */ + creationDateEnd: string; +} + +export interface ListInvoiceResponse { + /** + * A list of invoices from the time slice of the time series specified in the + * request. + */ + invoices: Invoice[]; + /** + * The index of the last item in the set of returned invoices. This can be used + * to seek further, pagination style. + */ + lastIndexOffset: string; + /** + * The index of the last item in the set of returned invoices. This can be used + * to seek backwards, pagination style. + */ + firstIndexOffset: string; +} + +export interface InvoiceSubscription { + /** + * If specified (non-zero), then we'll first start by sending out + * notifications for all added indexes with an add_index greater than this + * value. This allows callers to catch up on any events they missed while they + * weren't connected to the streaming RPC. + */ + addIndex: string; + /** + * If specified (non-zero), then we'll first start by sending out + * notifications for all settled indexes with an settle_index greater than + * this value. This allows callers to catch up on any events they missed while + * they weren't connected to the streaming RPC. + */ + settleIndex: string; +} + +export interface Payment { + /** The payment hash */ + paymentHash: string; + /** + * Deprecated, use value_sat or value_msat. + * + * @deprecated + */ + value: string; + /** + * Deprecated, use creation_time_ns + * + * @deprecated + */ + creationDate: string; + /** + * Deprecated, use fee_sat or fee_msat. + * + * @deprecated + */ + fee: string; + /** The payment preimage */ + paymentPreimage: string; + /** The value of the payment in satoshis */ + valueSat: string; + /** The value of the payment in milli-satoshis */ + valueMsat: string; + /** The optional payment request being fulfilled. */ + paymentRequest: string; + /** The status of the payment. */ + status: Payment_PaymentStatus; + /** The fee paid for this payment in satoshis */ + feeSat: string; + /** The fee paid for this payment in milli-satoshis */ + feeMsat: string; + /** The time in UNIX nanoseconds at which the payment was created. */ + creationTimeNs: string; + /** The HTLCs made in attempt to settle the payment. */ + htlcs: HTLCAttempt[]; + /** + * The creation index of this payment. Each payment can be uniquely identified + * by this index, which may not strictly increment by 1 for payments made in + * older versions of lnd. + */ + paymentIndex: string; + failureReason: PaymentFailureReason; + /** + * The custom TLV records that were sent to the first hop as part of the HTLC + * wire message for this payment. + */ + firstHopCustomRecords: { [key: string]: Uint8Array | string }; +} + +export enum Payment_PaymentStatus { + /** + * UNKNOWN - Deprecated. This status will never be returned. + * + * @deprecated + */ + UNKNOWN = 'UNKNOWN', + /** IN_FLIGHT - Payment has inflight HTLCs. */ + IN_FLIGHT = 'IN_FLIGHT', + /** SUCCEEDED - Payment is settled. */ + SUCCEEDED = 'SUCCEEDED', + /** FAILED - Payment is failed. */ + FAILED = 'FAILED', + /** INITIATED - Payment is created and has not attempted any HTLCs. */ + INITIATED = 'INITIATED', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export interface Payment_FirstHopCustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + +export interface HTLCAttempt { + /** The unique ID that is used for this attempt. */ + attemptId: string; + /** The status of the HTLC. */ + status: HTLCAttempt_HTLCStatus; + /** The route taken by this HTLC. */ + route: Route | undefined; + /** The time in UNIX nanoseconds at which this HTLC was sent. */ + attemptTimeNs: string; + /** + * The time in UNIX nanoseconds at which this HTLC was settled or failed. + * This value will not be set if the HTLC is still IN_FLIGHT. + */ + resolveTimeNs: string; + /** Detailed htlc failure info. */ + failure: Failure | undefined; + /** The preimage that was used to settle the HTLC. */ + preimage: Uint8Array | string; +} + +export enum HTLCAttempt_HTLCStatus { + IN_FLIGHT = 'IN_FLIGHT', + SUCCEEDED = 'SUCCEEDED', + FAILED = 'FAILED', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export interface ListPaymentsRequest { + /** + * If true, then return payments that have not yet fully completed. This means + * that pending payments, as well as failed payments will show up if this + * field is set to true. This flag doesn't change the meaning of the indices, + * which are tied to individual payments. + */ + includeIncomplete: boolean; + /** + * The index of a payment that will be used as either the start or end of a + * query to determine which payments should be returned in the response. The + * index_offset is exclusive. In the case of a zero index_offset, the query + * will start with the oldest payment when paginating forwards, or will end + * with the most recent payment when paginating backwards. + */ + indexOffset: string; + /** The maximal number of payments returned in the response to this query. */ + maxPayments: string; + /** + * If set, the payments returned will result from seeking backwards from the + * specified index offset. This can be used to paginate backwards. The order + * of the returned payments is always oldest first (ascending index order). + */ + reversed: boolean; + /** + * If set, all payments (complete and incomplete, independent of the + * max_payments parameter) will be counted. Note that setting this to true will + * increase the run time of the call significantly on systems that have a lot + * of payments, as all of them have to be iterated through to be counted. + */ + countTotalPayments: boolean; + /** + * If set, returns all payments with a creation date greater than or equal + * to it. Measured in seconds since the unix epoch. + */ + creationDateStart: string; + /** + * If set, returns all payments with a creation date less than or equal to + * it. Measured in seconds since the unix epoch. + */ + creationDateEnd: string; +} + +export interface ListPaymentsResponse { + /** The list of payments */ + payments: Payment[]; + /** + * The index of the first item in the set of returned payments. This can be + * used as the index_offset to continue seeking backwards in the next request. + */ + firstIndexOffset: string; + /** + * The index of the last item in the set of returned payments. This can be used + * as the index_offset to continue seeking forwards in the next request. + */ + lastIndexOffset: string; + /** + * Will only be set if count_total_payments in the request was set. Represents + * the total number of payments (complete and incomplete, independent of the + * number of payments requested in the query) currently present in the payments + * database. + */ + totalNumPayments: string; +} + +export interface DeletePaymentRequest { + /** Payment hash to delete. */ + paymentHash: Uint8Array | string; + /** Only delete failed HTLCs from the payment, not the payment itself. */ + failedHtlcsOnly: boolean; +} + +export interface DeleteAllPaymentsRequest { + /** Only delete failed payments. */ + failedPaymentsOnly: boolean; + /** Only delete failed HTLCs from payments, not the payment itself. */ + failedHtlcsOnly: boolean; + /** + * Delete all payments. NOTE: Using this option requires careful + * consideration as it is a destructive operation. + */ + allPayments: boolean; +} + +export interface DeletePaymentResponse {} + +export interface DeleteAllPaymentsResponse {} + +export interface AbandonChannelRequest { + channelPoint: ChannelPoint | undefined; + pendingFundingShimOnly: boolean; + /** + * Override the requirement for being in dev mode by setting this to true and + * confirming the user knows what they are doing and this is a potential foot + * gun to lose funds if used on active channels. + */ + iKnowWhatIAmDoing: boolean; +} + +export interface AbandonChannelResponse {} + +export interface DebugLevelRequest { + show: boolean; + levelSpec: string; +} + +export interface DebugLevelResponse { + subSystems: string; +} + +export interface PayReqString { + /** The payment request string to be decoded */ + payReq: string; +} + +export interface PayReq { + destination: string; + paymentHash: string; + numSatoshis: string; + timestamp: string; + expiry: string; + description: string; + descriptionHash: string; + fallbackAddr: string; + cltvExpiry: string; + routeHints: RouteHint[]; + paymentAddr: Uint8Array | string; + numMsat: string; + features: { [key: number]: Feature }; + blindedPaths: BlindedPaymentPath[]; +} + +export interface PayReq_FeaturesEntry { + key: number; + value: Feature | undefined; +} + +export interface Feature { + name: string; + isRequired: boolean; + isKnown: boolean; +} + +export interface FeeReportRequest {} + +export interface ChannelFeeReport { + /** The short channel id that this fee report belongs to. */ + chanId: string; + /** The channel that this fee report belongs to. */ + channelPoint: string; + /** The base fee charged regardless of the number of milli-satoshis sent. */ + baseFeeMsat: string; + /** + * The amount charged per milli-satoshis transferred expressed in + * millionths of a satoshi. + */ + feePerMil: string; + /** + * The effective fee rate in milli-satoshis. Computed by dividing the + * fee_per_mil value by 1 million. + */ + feeRate: number; + /** The base fee charged regardless of the number of milli-satoshis sent. */ + inboundBaseFeeMsat: number; + /** + * The amount charged per milli-satoshis transferred expressed in + * millionths of a satoshi. + */ + inboundFeePerMil: number; +} + +export interface FeeReportResponse { + /** + * An array of channel fee reports which describes the current fee schedule + * for each channel. + */ + channelFees: ChannelFeeReport[]; + /** + * The total amount of fee revenue (in satoshis) the switch has collected + * over the past 24 hrs. + */ + dayFeeSum: string; + /** + * The total amount of fee revenue (in satoshis) the switch has collected + * over the past 1 week. + */ + weekFeeSum: string; + /** + * The total amount of fee revenue (in satoshis) the switch has collected + * over the past 1 month. + */ + monthFeeSum: string; +} + +export interface InboundFee { + /** + * The inbound base fee charged regardless of the number of milli-satoshis + * received in the channel. By default, only negative values are accepted. + */ + baseFeeMsat: number; + /** + * The effective inbound fee rate in micro-satoshis (parts per million). + * By default, only negative values are accepted. + */ + feeRatePpm: number; +} + +export interface PolicyUpdateRequest { + /** If set, then this update applies to all currently active channels. */ + global: boolean | undefined; + /** If set, this update will target a specific channel. */ + chanPoint: ChannelPoint | undefined; + /** The base fee charged regardless of the number of milli-satoshis sent. */ + baseFeeMsat: string; + /** + * The effective fee rate in milli-satoshis. The precision of this value + * goes up to 6 decimal places, so 1e-6. + */ + feeRate: number; + /** The effective fee rate in micro-satoshis (parts per million). */ + feeRatePpm: number; + /** The required timelock delta for HTLCs forwarded over the channel. */ + timeLockDelta: number; + /** + * If set, the maximum HTLC size in milli-satoshis. If unset, the maximum + * HTLC will be unchanged. + */ + maxHtlcMsat: string; + /** + * The minimum HTLC size in milli-satoshis. Only applied if + * min_htlc_msat_specified is true. + */ + minHtlcMsat: string; + /** If true, min_htlc_msat is applied. */ + minHtlcMsatSpecified: boolean; + /** + * Optional inbound fee. If unset, the previously set value will be + * retained [EXPERIMENTAL]. + */ + inboundFee: InboundFee | undefined; +} + +export interface FailedUpdate { + /** The outpoint in format txid:n */ + outpoint: OutPoint | undefined; + /** Reason for the policy update failure. */ + reason: UpdateFailure; + /** A string representation of the policy update error. */ + updateError: string; +} + +export interface PolicyUpdateResponse { + /** List of failed policy updates. */ + failedUpdates: FailedUpdate[]; +} + +export interface ForwardingHistoryRequest { + /** + * Start time is the starting point of the forwarding history request. All + * records beyond this point will be included, respecting the end time, and + * the index offset. + */ + startTime: string; + /** + * End time is the end point of the forwarding history request. The + * response will carry at most 50k records between the start time and the + * end time. The index offset can be used to implement pagination. + */ + endTime: string; + /** + * Index offset is the offset in the time series to start at. As each + * response can only contain 50k records, callers can use this to skip + * around within a packed time series. + */ + indexOffset: number; + /** The max number of events to return in the response to this query. */ + numMaxEvents: number; + /** + * Informs the server if the peer alias should be looked up for each + * forwarding event. + */ + peerAliasLookup: boolean; +} + +export interface ForwardingEvent { + /** + * Timestamp is the time (unix epoch offset) that this circuit was + * completed. Deprecated by timestamp_ns. + * + * @deprecated + */ + timestamp: string; + /** The incoming channel ID that carried the HTLC that created the circuit. */ + chanIdIn: string; + /** + * The outgoing channel ID that carried the preimage that completed the + * circuit. + */ + chanIdOut: string; + /** + * The total amount (in satoshis) of the incoming HTLC that created half + * the circuit. + */ + amtIn: string; + /** + * The total amount (in satoshis) of the outgoing HTLC that created the + * second half of the circuit. + */ + amtOut: string; + /** The total fee (in satoshis) that this payment circuit carried. */ + fee: string; + /** The total fee (in milli-satoshis) that this payment circuit carried. */ + feeMsat: string; + /** + * The total amount (in milli-satoshis) of the incoming HTLC that created + * half the circuit. + */ + amtInMsat: string; + /** + * The total amount (in milli-satoshis) of the outgoing HTLC that created + * the second half of the circuit. + */ + amtOutMsat: string; + /** + * The number of nanoseconds elapsed since January 1, 1970 UTC when this + * circuit was completed. + */ + timestampNs: string; + /** The peer alias of the incoming channel. */ + peerAliasIn: string; + /** The peer alias of the outgoing channel. */ + peerAliasOut: string; +} + +export interface ForwardingHistoryResponse { + /** + * A list of forwarding events from the time slice of the time series + * specified in the request. + */ + forwardingEvents: ForwardingEvent[]; + /** + * The index of the last time in the set of returned forwarding events. Can + * be used to seek further, pagination style. + */ + lastOffsetIndex: number; +} + +export interface ExportChannelBackupRequest { + /** The target channel point to obtain a back up for. */ + chanPoint: ChannelPoint | undefined; +} + +export interface ChannelBackup { + /** Identifies the channel that this backup belongs to. */ + chanPoint: ChannelPoint | undefined; + /** + * Is an encrypted single-chan backup. this can be passed to + * RestoreChannelBackups, or the WalletUnlocker Init and Unlock methods in + * order to trigger the recovery protocol. When using REST, this field must be + * encoded as base64. + */ + chanBackup: Uint8Array | string; +} + +export interface MultiChanBackup { + /** Is the set of all channels that are included in this multi-channel backup. */ + chanPoints: ChannelPoint[]; + /** + * A single encrypted blob containing all the static channel backups of the + * channel listed above. This can be stored as a single file or blob, and + * safely be replaced with any prior/future versions. When using REST, this + * field must be encoded as base64. + */ + multiChanBackup: Uint8Array | string; +} + +export interface ChanBackupExportRequest {} + +export interface ChanBackupSnapshot { + /** + * The set of new channels that have been added since the last channel backup + * snapshot was requested. + */ + singleChanBackups: ChannelBackups | undefined; + /** + * A multi-channel backup that covers all open channels currently known to + * lnd. + */ + multiChanBackup: MultiChanBackup | undefined; +} + +export interface ChannelBackups { + /** A set of single-chan static channel backups. */ + chanBackups: ChannelBackup[]; +} + +export interface RestoreChanBackupRequest { + /** The channels to restore as a list of channel/backup pairs. */ + chanBackups: ChannelBackups | undefined; + /** + * The channels to restore in the packed multi backup format. When using + * REST, this field must be encoded as base64. + */ + multiChanBackup: Uint8Array | string | undefined; +} + +export interface RestoreBackupResponse {} + +export interface ChannelBackupSubscription {} + +export interface VerifyChanBackupResponse {} + +export interface MacaroonPermission { + /** The entity a permission grants access to. */ + entity: string; + /** The action that is granted. */ + action: string; +} + +export interface BakeMacaroonRequest { + /** The list of permissions the new macaroon should grant. */ + permissions: MacaroonPermission[]; + /** The root key ID used to create the macaroon, must be a positive integer. */ + rootKeyId: string; + /** + * Informs the RPC on whether to allow external permissions that LND is not + * aware of. + */ + allowExternalPermissions: boolean; +} + +export interface BakeMacaroonResponse { + /** The hex encoded macaroon, serialized in binary format. */ + macaroon: string; +} + +export interface ListMacaroonIDsRequest {} + +export interface ListMacaroonIDsResponse { + /** The list of root key IDs that are in use. */ + rootKeyIds: string[]; +} + +export interface DeleteMacaroonIDRequest { + /** The root key ID to be removed. */ + rootKeyId: string; +} + +export interface DeleteMacaroonIDResponse { + /** A boolean indicates that the deletion is successful. */ + deleted: boolean; +} + +export interface MacaroonPermissionList { + /** A list of macaroon permissions. */ + permissions: MacaroonPermission[]; +} + +export interface ListPermissionsRequest {} + +export interface ListPermissionsResponse { + /** + * A map between all RPC method URIs and their required macaroon permissions to + * access them. + */ + methodPermissions: { [key: string]: MacaroonPermissionList }; +} + +export interface ListPermissionsResponse_MethodPermissionsEntry { + key: string; + value: MacaroonPermissionList | undefined; +} + +export interface Failure { + /** Failure code as defined in the Lightning spec */ + code: Failure_FailureCode; + /** An optional channel update message. */ + channelUpdate: ChannelUpdate | undefined; + /** A failure type-dependent htlc value. */ + htlcMsat: string; + /** The sha256 sum of the onion payload. */ + onionSha256: Uint8Array | string; + /** A failure type-dependent cltv expiry value. */ + cltvExpiry: number; + /** A failure type-dependent flags value. */ + flags: number; + /** + * The position in the path of the intermediate or final node that generated + * the failure message. Position zero is the sender node. + */ + failureSourceIndex: number; + /** A failure type-dependent block height. */ + height: number; +} + +export enum Failure_FailureCode { + /** + * RESERVED - The numbers assigned in this enumeration match the failure codes as + * defined in BOLT #4. Because protobuf 3 requires enums to start with 0, + * a RESERVED value is added. + */ + RESERVED = 'RESERVED', + INCORRECT_OR_UNKNOWN_PAYMENT_DETAILS = 'INCORRECT_OR_UNKNOWN_PAYMENT_DETAILS', + INCORRECT_PAYMENT_AMOUNT = 'INCORRECT_PAYMENT_AMOUNT', + FINAL_INCORRECT_CLTV_EXPIRY = 'FINAL_INCORRECT_CLTV_EXPIRY', + FINAL_INCORRECT_HTLC_AMOUNT = 'FINAL_INCORRECT_HTLC_AMOUNT', + FINAL_EXPIRY_TOO_SOON = 'FINAL_EXPIRY_TOO_SOON', + INVALID_REALM = 'INVALID_REALM', + EXPIRY_TOO_SOON = 'EXPIRY_TOO_SOON', + INVALID_ONION_VERSION = 'INVALID_ONION_VERSION', + INVALID_ONION_HMAC = 'INVALID_ONION_HMAC', + INVALID_ONION_KEY = 'INVALID_ONION_KEY', + AMOUNT_BELOW_MINIMUM = 'AMOUNT_BELOW_MINIMUM', + FEE_INSUFFICIENT = 'FEE_INSUFFICIENT', + INCORRECT_CLTV_EXPIRY = 'INCORRECT_CLTV_EXPIRY', + CHANNEL_DISABLED = 'CHANNEL_DISABLED', + TEMPORARY_CHANNEL_FAILURE = 'TEMPORARY_CHANNEL_FAILURE', + REQUIRED_NODE_FEATURE_MISSING = 'REQUIRED_NODE_FEATURE_MISSING', + REQUIRED_CHANNEL_FEATURE_MISSING = 'REQUIRED_CHANNEL_FEATURE_MISSING', + UNKNOWN_NEXT_PEER = 'UNKNOWN_NEXT_PEER', + TEMPORARY_NODE_FAILURE = 'TEMPORARY_NODE_FAILURE', + PERMANENT_NODE_FAILURE = 'PERMANENT_NODE_FAILURE', + PERMANENT_CHANNEL_FAILURE = 'PERMANENT_CHANNEL_FAILURE', + EXPIRY_TOO_FAR = 'EXPIRY_TOO_FAR', + MPP_TIMEOUT = 'MPP_TIMEOUT', + INVALID_ONION_PAYLOAD = 'INVALID_ONION_PAYLOAD', + INVALID_ONION_BLINDING = 'INVALID_ONION_BLINDING', + /** INTERNAL_FAILURE - An internal error occurred. */ + INTERNAL_FAILURE = 'INTERNAL_FAILURE', + /** UNKNOWN_FAILURE - The error source is known, but the failure itself couldn't be decoded. */ + UNKNOWN_FAILURE = 'UNKNOWN_FAILURE', + /** + * UNREADABLE_FAILURE - An unreadable failure result is returned if the received failure message + * cannot be decrypted. In that case the error source is unknown. + */ + UNREADABLE_FAILURE = 'UNREADABLE_FAILURE', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export interface ChannelUpdate { + /** + * The signature that validates the announced data and proves the ownership + * of node id. + */ + signature: Uint8Array | string; + /** + * The target chain that this channel was opened within. This value + * should be the genesis hash of the target chain. Along with the short + * channel ID, this uniquely identifies the channel globally in a + * blockchain. + */ + chainHash: Uint8Array | string; + /** The unique description of the funding transaction. */ + chanId: string; + /** + * A timestamp that allows ordering in the case of multiple announcements. + * We should ignore the message if timestamp is not greater than the + * last-received. + */ + timestamp: number; + /** + * The bitfield that describes whether optional fields are present in this + * update. Currently, the least-significant bit must be set to 1 if the + * optional field MaxHtlc is present. + */ + messageFlags: number; + /** + * The bitfield that describes additional meta-data concerning how the + * update is to be interpreted. Currently, the least-significant bit must be + * set to 0 if the creating node corresponds to the first node in the + * previously sent channel announcement and 1 otherwise. If the second bit + * is set, then the channel is set to be disabled. + */ + channelFlags: number; + /** + * The minimum number of blocks this node requires to be added to the expiry + * of HTLCs. This is a security parameter determined by the node operator. + * This value represents the required gap between the time locks of the + * incoming and outgoing HTLC's set to this node. + */ + timeLockDelta: number; + /** The minimum HTLC value which will be accepted. */ + htlcMinimumMsat: string; + /** + * The base fee that must be used for incoming HTLC's to this particular + * channel. This value will be tacked onto the required for a payment + * independent of the size of the payment. + */ + baseFee: number; + /** The fee rate that will be charged per millionth of a satoshi. */ + feeRate: number; + /** The maximum HTLC value which will be accepted. */ + htlcMaximumMsat: string; + /** + * The set of data that was appended to this message, some of which we may + * not actually know how to iterate or parse. By holding onto this data, we + * ensure that we're able to properly validate the set of signatures that + * cover these new fields, and ensure we're able to make upgrades to the + * network in a forwards compatible manner. + */ + extraOpaqueData: Uint8Array | string; +} + +export interface MacaroonId { + nonce: Uint8Array | string; + storageId: Uint8Array | string; + ops: Op[]; +} + +export interface Op { + entity: string; + actions: string[]; +} + +export interface CheckMacPermRequest { + macaroon: Uint8Array | string; + permissions: MacaroonPermission[]; + fullMethod: string; +} + +export interface CheckMacPermResponse { + valid: boolean; +} + +export interface RPCMiddlewareRequest { + /** + * The unique ID of the intercepted original gRPC request. Useful for mapping + * request to response when implementing full duplex message interception. For + * streaming requests, this will be the same ID for all incoming and outgoing + * middleware intercept messages of the _same_ stream. + */ + requestId: string; + /** + * The raw bytes of the complete macaroon as sent by the gRPC client in the + * original request. This might be empty for a request that doesn't require + * macaroons such as the wallet unlocker RPCs. + */ + rawMacaroon: Uint8Array | string; + /** + * The parsed condition of the macaroon's custom caveat for convenient access. + * This field only contains the value of the custom caveat that the handling + * middleware has registered itself for. The condition _must_ be validated for + * messages of intercept_type stream_auth and request! + */ + customCaveatCondition: string; + /** + * Intercept stream authentication: each new streaming RPC call that is + * initiated against lnd and contains the middleware's custom macaroon + * caveat can be approved or denied based upon the macaroon in the stream + * header. This message will only be sent for streaming RPCs, unary RPCs + * must handle the macaroon authentication in the request interception to + * avoid an additional message round trip between lnd and the middleware. + */ + streamAuth: StreamAuth | undefined; + /** + * Intercept incoming gRPC client request message: all incoming messages, + * both on streaming and unary RPCs, are forwarded to the middleware for + * inspection. For unary RPC messages the middleware is also expected to + * validate the custom macaroon caveat of the request. + */ + request: RPCMessage | undefined; + /** + * Intercept outgoing gRPC response message: all outgoing messages, both on + * streaming and unary RPCs, are forwarded to the middleware for inspection + * and amendment. The response in this message is the original response as + * it was generated by the main RPC server. It can either be accepted + * (=forwarded to the client), replaced/overwritten with a new message of + * the same type, or replaced by an error message. + */ + response: RPCMessage | undefined; + /** + * This is used to indicate to the client that the server has successfully + * registered the interceptor. This is only used in the very first message + * that the server sends to the client after the client sends the server + * the middleware registration message. + */ + regComplete: boolean | undefined; + /** + * The unique message ID of this middleware intercept message. There can be + * multiple middleware intercept messages per single gRPC request (one for the + * incoming request and one for the outgoing response) or gRPC stream (one for + * each incoming message and one for each outgoing response). This message ID + * must be referenced when responding (accepting/rejecting/modifying) to an + * intercept message. + */ + msgId: string; +} + +export interface StreamAuth { + /** + * The full URI (in the format /./MethodName, for + * example /lnrpc.Lightning/GetInfo) of the streaming RPC method that was just + * established. + */ + methodFullUri: string; +} + +export interface RPCMessage { + /** + * The full URI (in the format /./MethodName, for + * example /lnrpc.Lightning/GetInfo) of the RPC method the message was sent + * to/from. + */ + methodFullUri: string; + /** Indicates whether the message was sent over a streaming RPC method or not. */ + streamRpc: boolean; + /** + * The full canonical gRPC name of the message type (in the format + * .TypeName, for example lnrpc.GetInfoRequest). In case of an + * error being returned from lnd, this simply contains the string "error". + */ + typeName: string; + /** + * The full content of the gRPC message, serialized in the binary protobuf + * format. + */ + serialized: Uint8Array | string; + /** + * Indicates that the response from lnd was an error, not a gRPC response. If + * this is set to true then the type_name contains the string "error" and + * serialized contains the error string. + */ + isError: boolean; +} + +export interface RPCMiddlewareResponse { + /** + * The request message ID this response refers to. Must always be set when + * giving feedback to an intercept but is ignored for the initial registration + * message. + */ + refMsgId: string; + /** + * The registration message identifies the middleware that's being + * registered in lnd. The registration message must be sent immediately + * after initiating the RegisterRpcMiddleware stream, otherwise lnd will + * time out the attempt and terminate the request. NOTE: The middleware + * will only receive interception messages for requests that contain a + * macaroon with the custom caveat that the middleware declares it is + * responsible for handling in the registration message! As a security + * measure, _no_ middleware can intercept requests made with _unencumbered_ + * macaroons! + */ + register: MiddlewareRegistration | undefined; + /** + * The middleware received an interception request and gives feedback to + * it. The request_id indicates what message the feedback refers to. + */ + feedback: InterceptFeedback | undefined; +} + +export interface MiddlewareRegistration { + /** + * The name of the middleware to register. The name should be as informative + * as possible and is logged on registration. + */ + middlewareName: string; + /** + * The name of the custom macaroon caveat that this middleware is responsible + * for. Only requests/responses that contain a macaroon with the registered + * custom caveat are forwarded for interception to the middleware. The + * exception being the read-only mode: All requests/responses are forwarded to + * a middleware that requests read-only access but such a middleware won't be + * allowed to _alter_ responses. As a security measure, _no_ middleware can + * change responses to requests made with _unencumbered_ macaroons! + * NOTE: Cannot be used at the same time as read_only_mode. + */ + customMacaroonCaveatName: string; + /** + * Instead of defining a custom macaroon caveat name a middleware can register + * itself for read-only access only. In that mode all requests/responses are + * forwarded to the middleware but the middleware isn't allowed to alter any of + * the responses. + * NOTE: Cannot be used at the same time as custom_macaroon_caveat_name. + */ + readOnlyMode: boolean; +} + +export interface InterceptFeedback { + /** + * The error to return to the user. If this is non-empty, the incoming gRPC + * stream/request is aborted and the error is returned to the gRPC client. If + * this value is empty, it means the middleware accepts the stream/request/ + * response and the processing of it can continue. + */ + error: string; + /** + * A boolean indicating that the gRPC message should be replaced/overwritten. + * This boolean is needed because in protobuf an empty message is serialized as + * a 0-length or nil byte slice and we wouldn't be able to distinguish between + * an empty replacement message and the "don't replace anything" case. + */ + replaceResponse: boolean; + /** + * If the replace_response field is set to true, this field must contain the + * binary serialized gRPC message in the protobuf format. + */ + replacementSerialized: Uint8Array | string; +} + +/** Lightning is the main RPC server of the daemon. */ +export interface Lightning { + /** + * lncli: `walletbalance` + * WalletBalance returns total unspent outputs(confirmed and unconfirmed), all + * confirmed unspent outputs and all unconfirmed unspent outputs under control + * of the wallet. + */ + walletBalance( + request?: DeepPartial + ): Promise; + /** + * lncli: `channelbalance` + * ChannelBalance returns a report on the total funds across all open channels, + * categorized in local/remote, pending local/remote and unsettled local/remote + * balances. + */ + channelBalance( + request?: DeepPartial + ): Promise; + /** + * lncli: `listchaintxns` + * GetTransactions returns a list describing all the known transactions + * relevant to the wallet. + */ + getTransactions( + request?: DeepPartial + ): Promise; + /** + * lncli: `estimatefee` + * EstimateFee asks the chain backend to estimate the fee rate and total fees + * for a transaction that pays to multiple specified outputs. + * + * When using REST, the `AddrToAmount` map type can be set by appending + * `&AddrToAmount[
]=` to the URL. Unfortunately this + * map type doesn't appear in the REST API documentation because of a bug in + * the grpc-gateway library. + */ + estimateFee( + request?: DeepPartial + ): Promise; + /** + * lncli: `sendcoins` + * SendCoins executes a request to send coins to a particular address. Unlike + * SendMany, this RPC call only allows creating a single output at a time. If + * neither target_conf, or sat_per_vbyte are set, then the internal wallet will + * consult its fee model to determine a fee for the default confirmation + * target. + */ + sendCoins( + request?: DeepPartial + ): Promise; + /** + * lncli: `listunspent` + * Deprecated, use walletrpc.ListUnspent instead. + * + * ListUnspent returns a list of all utxos spendable by the wallet with a + * number of confirmations between the specified minimum and maximum. + */ + listUnspent( + request?: DeepPartial + ): Promise; + /** + * SubscribeTransactions creates a uni-directional stream from the server to + * the client in which any newly discovered transactions relevant to the + * wallet are sent over. + */ + subscribeTransactions( + request?: DeepPartial, + onMessage?: (msg: Transaction) => void, + onError?: (err: Error) => void + ): void; + /** + * lncli: `sendmany` + * SendMany handles a request for a transaction that creates multiple specified + * outputs in parallel. If neither target_conf, or sat_per_vbyte are set, then + * the internal wallet will consult its fee model to determine a fee for the + * default confirmation target. + */ + sendMany(request?: DeepPartial): Promise; + /** + * lncli: `newaddress` + * NewAddress creates a new address under control of the local wallet. + */ + newAddress( + request?: DeepPartial + ): Promise; + /** + * lncli: `signmessage` + * SignMessage signs a message with this node's private key. The returned + * signature string is `zbase32` encoded and pubkey recoverable, meaning that + * only the message digest and signature are needed for verification. + */ + signMessage( + request?: DeepPartial + ): Promise; + /** + * lncli: `verifymessage` + * VerifyMessage verifies a signature over a message and recovers the signer's + * public key. The signature is only deemed valid if the recovered public key + * corresponds to a node key in the public Lightning network. The signature + * must be zbase32 encoded and signed by an active node in the resident node's + * channel database. In addition to returning the validity of the signature, + * VerifyMessage also returns the recovered pubkey from the signature. + */ + verifyMessage( + request?: DeepPartial + ): Promise; + /** + * lncli: `connect` + * ConnectPeer attempts to establish a connection to a remote peer. This is at + * the networking level, and is used for communication between nodes. This is + * distinct from establishing a channel with a peer. + */ + connectPeer( + request?: DeepPartial + ): Promise; + /** + * lncli: `disconnect` + * DisconnectPeer attempts to disconnect one peer from another identified by a + * given pubKey. In the case that we currently have a pending or active channel + * with the target peer, then this action will be not be allowed. + */ + disconnectPeer( + request?: DeepPartial + ): Promise; + /** + * lncli: `listpeers` + * ListPeers returns a verbose listing of all currently active peers. + */ + listPeers( + request?: DeepPartial + ): Promise; + /** + * SubscribePeerEvents creates a uni-directional stream from the server to + * the client in which any events relevant to the state of peers are sent + * over. Events include peers going online and offline. + */ + subscribePeerEvents( + request?: DeepPartial, + onMessage?: (msg: PeerEvent) => void, + onError?: (err: Error) => void + ): void; + /** + * lncli: `getinfo` + * GetInfo returns general information concerning the lightning node including + * it's identity pubkey, alias, the chains it is connected to, and information + * concerning the number of open+pending channels. + */ + getInfo(request?: DeepPartial): Promise; + /** + * lncli: 'getdebuginfo' + * GetDebugInfo returns debug information concerning the state of the daemon + * and its subsystems. This includes the full configuration and the latest log + * entries from the log file. + */ + getDebugInfo( + request?: DeepPartial + ): Promise; + /** + * lncli: `getrecoveryinfo` + * GetRecoveryInfo returns information concerning the recovery mode including + * whether it's in a recovery mode, whether the recovery is finished, and the + * progress made so far. + */ + getRecoveryInfo( + request?: DeepPartial + ): Promise; + /** + * lncli: `pendingchannels` + * PendingChannels returns a list of all the channels that are currently + * considered "pending". A channel is pending if it has finished the funding + * workflow and is waiting for confirmations for the funding txn, or is in the + * process of closure, either initiated cooperatively or non-cooperatively. + */ + pendingChannels( + request?: DeepPartial + ): Promise; + /** + * lncli: `listchannels` + * ListChannels returns a description of all the open channels that this node + * is a participant in. + */ + listChannels( + request?: DeepPartial + ): Promise; + /** + * SubscribeChannelEvents creates a uni-directional stream from the server to + * the client in which any updates relevant to the state of the channels are + * sent over. Events include new active channels, inactive channels, and closed + * channels. + */ + subscribeChannelEvents( + request?: DeepPartial, + onMessage?: (msg: ChannelEventUpdate) => void, + onError?: (err: Error) => void + ): void; + /** + * lncli: `closedchannels` + * ClosedChannels returns a description of all the closed channels that + * this node was a participant in. + */ + closedChannels( + request?: DeepPartial + ): Promise; + /** + * OpenChannelSync is a synchronous version of the OpenChannel RPC call. This + * call is meant to be consumed by clients to the REST proxy. As with all + * other sync calls, all byte slices are intended to be populated as hex + * encoded strings. + */ + openChannelSync( + request?: DeepPartial + ): Promise; + /** + * lncli: `openchannel` + * OpenChannel attempts to open a singly funded channel specified in the + * request to a remote peer. Users are able to specify a target number of + * blocks that the funding transaction should be confirmed in, or a manual fee + * rate to us for the funding transaction. If neither are specified, then a + * lax block confirmation target is used. Each OpenStatusUpdate will return + * the pending channel ID of the in-progress channel. Depending on the + * arguments specified in the OpenChannelRequest, this pending channel ID can + * then be used to manually progress the channel funding flow. + */ + openChannel( + request?: DeepPartial, + onMessage?: (msg: OpenStatusUpdate) => void, + onError?: (err: Error) => void + ): void; + /** + * lncli: `batchopenchannel` + * BatchOpenChannel attempts to open multiple single-funded channels in a + * single transaction in an atomic way. This means either all channel open + * requests succeed at once or all attempts are aborted if any of them fail. + * This is the safer variant of using PSBTs to manually fund a batch of + * channels through the OpenChannel RPC. + */ + batchOpenChannel( + request?: DeepPartial + ): Promise; + /** + * FundingStateStep is an advanced funding related call that allows the caller + * to either execute some preparatory steps for a funding workflow, or + * manually progress a funding workflow. The primary way a funding flow is + * identified is via its pending channel ID. As an example, this method can be + * used to specify that we're expecting a funding flow for a particular + * pending channel ID, for which we need to use specific parameters. + * Alternatively, this can be used to interactively drive PSBT signing for + * funding for partially complete funding transactions. + */ + fundingStateStep( + request?: DeepPartial + ): Promise; + /** + * ChannelAcceptor dispatches a bi-directional streaming RPC in which + * OpenChannel requests are sent to the client and the client responds with + * a boolean that tells LND whether or not to accept the channel. This allows + * node operators to specify their own criteria for accepting inbound channels + * through a single persistent connection. + */ + channelAcceptor( + request?: DeepPartial, + onMessage?: (msg: ChannelAcceptRequest) => void, + onError?: (err: Error) => void + ): void; + /** + * lncli: `closechannel` + * CloseChannel attempts to close an active channel identified by its channel + * outpoint (ChannelPoint). The actions of this method can additionally be + * augmented to attempt a force close after a timeout period in the case of an + * inactive peer. If a non-force close (cooperative closure) is requested, + * then the user can specify either a target number of blocks until the + * closure transaction is confirmed, or a manual fee rate. If neither are + * specified, then a default lax, block confirmation target is used. + */ + closeChannel( + request?: DeepPartial, + onMessage?: (msg: CloseStatusUpdate) => void, + onError?: (err: Error) => void + ): void; + /** + * lncli: `abandonchannel` + * AbandonChannel removes all channel state from the database except for a + * close summary. This method can be used to get rid of permanently unusable + * channels due to bugs fixed in newer versions of lnd. This method can also be + * used to remove externally funded channels where the funding transaction was + * never broadcast. Only available for non-externally funded channels in dev + * build. + */ + abandonChannel( + request?: DeepPartial + ): Promise; + /** + * lncli: `sendpayment` + * Deprecated, use routerrpc.SendPaymentV2. SendPayment dispatches a + * bi-directional streaming RPC for sending payments through the Lightning + * Network. A single RPC invocation creates a persistent bi-directional + * stream allowing clients to rapidly send payments through the Lightning + * Network with a single persistent connection. + * + * @deprecated + */ + sendPayment( + request?: DeepPartial, + onMessage?: (msg: SendResponse) => void, + onError?: (err: Error) => void + ): void; + /** + * SendPaymentSync is the synchronous non-streaming version of SendPayment. + * This RPC is intended to be consumed by clients of the REST proxy. + * Additionally, this RPC expects the destination's public key and the payment + * hash (if any) to be encoded as hex strings. + */ + sendPaymentSync(request?: DeepPartial): Promise; + /** + * lncli: `sendtoroute` + * Deprecated, use routerrpc.SendToRouteV2. SendToRoute is a bi-directional + * streaming RPC for sending payment through the Lightning Network. This + * method differs from SendPayment in that it allows users to specify a full + * route manually. This can be used for things like rebalancing, and atomic + * swaps. + * + * @deprecated + */ + sendToRoute( + request?: DeepPartial, + onMessage?: (msg: SendResponse) => void, + onError?: (err: Error) => void + ): void; + /** + * SendToRouteSync is a synchronous version of SendToRoute. It Will block + * until the payment either fails or succeeds. + */ + sendToRouteSync( + request?: DeepPartial + ): Promise; + /** + * lncli: `addinvoice` + * AddInvoice attempts to add a new invoice to the invoice database. Any + * duplicated invoices are rejected, therefore all invoices *must* have a + * unique payment preimage. + */ + addInvoice(request?: DeepPartial): Promise; + /** + * lncli: `listinvoices` + * ListInvoices returns a list of all the invoices currently stored within the + * database. Any active debug invoices are ignored. It has full support for + * paginated responses, allowing users to query for specific invoices through + * their add_index. This can be done by using either the first_index_offset or + * last_index_offset fields included in the response as the index_offset of the + * next request. By default, the first 100 invoices created will be returned. + * Backwards pagination is also supported through the Reversed flag. + */ + listInvoices( + request?: DeepPartial + ): Promise; + /** + * lncli: `lookupinvoice` + * LookupInvoice attempts to look up an invoice according to its payment hash. + * The passed payment hash *must* be exactly 32 bytes, if not, an error is + * returned. + */ + lookupInvoice(request?: DeepPartial): Promise; + /** + * SubscribeInvoices returns a uni-directional stream (server -> client) for + * notifying the client of newly added/settled invoices. The caller can + * optionally specify the add_index and/or the settle_index. If the add_index + * is specified, then we'll first start by sending add invoice events for all + * invoices with an add_index greater than the specified value. If the + * settle_index is specified, then next, we'll send out all settle events for + * invoices with a settle_index greater than the specified value. One or both + * of these fields can be set. If no fields are set, then we'll only send out + * the latest add/settle events. + */ + subscribeInvoices( + request?: DeepPartial, + onMessage?: (msg: Invoice) => void, + onError?: (err: Error) => void + ): void; + /** + * lncli: `decodepayreq` + * DecodePayReq takes an encoded payment request string and attempts to decode + * it, returning a full description of the conditions encoded within the + * payment request. + */ + decodePayReq(request?: DeepPartial): Promise; + /** + * lncli: `listpayments` + * ListPayments returns a list of all outgoing payments. + */ + listPayments( + request?: DeepPartial + ): Promise; + /** + * lncli: `deletepayments` + * DeletePayment deletes an outgoing payment from DB. Note that it will not + * attempt to delete an In-Flight payment, since that would be unsafe. + */ + deletePayment( + request?: DeepPartial + ): Promise; + /** + * lncli: `deletepayments --all` + * DeleteAllPayments deletes all outgoing payments from DB. Note that it will + * not attempt to delete In-Flight payments, since that would be unsafe. + */ + deleteAllPayments( + request?: DeepPartial + ): Promise; + /** + * lncli: `describegraph` + * DescribeGraph returns a description of the latest graph state from the + * point of view of the node. The graph information is partitioned into two + * components: all the nodes/vertexes, and all the edges that connect the + * vertexes themselves. As this is a directed graph, the edges also contain + * the node directional specific routing policy which includes: the time lock + * delta, fee information, etc. + */ + describeGraph( + request?: DeepPartial + ): Promise; + /** + * lncli: `getnodemetrics` + * GetNodeMetrics returns node metrics calculated from the graph. Currently + * the only supported metric is betweenness centrality of individual nodes. + */ + getNodeMetrics( + request?: DeepPartial + ): Promise; + /** + * lncli: `getchaninfo` + * GetChanInfo returns the latest authenticated network announcement for the + * given channel identified by its channel ID: an 8-byte integer which + * uniquely identifies the location of transaction's funding output within the + * blockchain. + */ + getChanInfo(request?: DeepPartial): Promise; + /** + * lncli: `getnodeinfo` + * GetNodeInfo returns the latest advertised, aggregated, and authenticated + * channel information for the specified node identified by its public key. + */ + getNodeInfo(request?: DeepPartial): Promise; + /** + * lncli: `queryroutes` + * QueryRoutes attempts to query the daemon's Channel Router for a possible + * route to a target destination capable of carrying a specific amount of + * satoshis. The returned route contains the full details required to craft and + * send an HTLC, also including the necessary information that should be + * present within the Sphinx packet encapsulated within the HTLC. + * + * When using REST, the `dest_custom_records` map type can be set by appending + * `&dest_custom_records[]=` + * to the URL. Unfortunately this map type doesn't appear in the REST API + * documentation because of a bug in the grpc-gateway library. + */ + queryRoutes( + request?: DeepPartial + ): Promise; + /** + * lncli: `getnetworkinfo` + * GetNetworkInfo returns some basic stats about the known channel graph from + * the point of view of the node. + */ + getNetworkInfo( + request?: DeepPartial + ): Promise; + /** + * lncli: `stop` + * StopDaemon will send a shutdown request to the interrupt handler, triggering + * a graceful shutdown of the daemon. + */ + stopDaemon(request?: DeepPartial): Promise; + /** + * SubscribeChannelGraph launches a streaming RPC that allows the caller to + * receive notifications upon any changes to the channel graph topology from + * the point of view of the responding node. Events notified include: new + * nodes coming online, nodes updating their authenticated attributes, new + * channels being advertised, updates in the routing policy for a directional + * channel edge, and when channels are closed on-chain. + */ + subscribeChannelGraph( + request?: DeepPartial, + onMessage?: (msg: GraphTopologyUpdate) => void, + onError?: (err: Error) => void + ): void; + /** + * lncli: `debuglevel` + * DebugLevel allows a caller to programmatically set the logging verbosity of + * lnd. The logging can be targeted according to a coarse daemon-wide logging + * level, or in a granular fashion to specify the logging for a target + * sub-system. + */ + debugLevel( + request?: DeepPartial + ): Promise; + /** + * lncli: `feereport` + * FeeReport allows the caller to obtain a report detailing the current fee + * schedule enforced by the node globally for each channel. + */ + feeReport( + request?: DeepPartial + ): Promise; + /** + * lncli: `updatechanpolicy` + * UpdateChannelPolicy allows the caller to update the fee schedule and + * channel policies for all channels globally, or a particular channel. + */ + updateChannelPolicy( + request?: DeepPartial + ): Promise; + /** + * lncli: `fwdinghistory` + * ForwardingHistory allows the caller to query the htlcswitch for a record of + * all HTLCs forwarded within the target time range, and integer offset + * within that time range, for a maximum number of events. If no maximum number + * of events is specified, up to 100 events will be returned. If no time-range + * is specified, then events will be returned in the order that they occured. + * + * A list of forwarding events are returned. The size of each forwarding event + * is 40 bytes, and the max message size able to be returned in gRPC is 4 MiB. + * As a result each message can only contain 50k entries. Each response has + * the index offset of the last entry. The index offset can be provided to the + * request to allow the caller to skip a series of records. + */ + forwardingHistory( + request?: DeepPartial + ): Promise; + /** + * lncli: `exportchanbackup` + * ExportChannelBackup attempts to return an encrypted static channel backup + * for the target channel identified by it channel point. The backup is + * encrypted with a key generated from the aezeed seed of the user. The + * returned backup can either be restored using the RestoreChannelBackup + * method once lnd is running, or via the InitWallet and UnlockWallet methods + * from the WalletUnlocker service. + */ + exportChannelBackup( + request?: DeepPartial + ): Promise; + /** + * ExportAllChannelBackups returns static channel backups for all existing + * channels known to lnd. A set of regular singular static channel backups for + * each channel are returned. Additionally, a multi-channel backup is returned + * as well, which contains a single encrypted blob containing the backups of + * each channel. + */ + exportAllChannelBackups( + request?: DeepPartial + ): Promise; + /** + * lncli: `verifychanbackup` + * VerifyChanBackup allows a caller to verify the integrity of a channel backup + * snapshot. This method will accept either a packed Single or a packed Multi. + * Specifying both will result in an error. + */ + verifyChanBackup( + request?: DeepPartial + ): Promise; + /** + * lncli: `restorechanbackup` + * RestoreChannelBackups accepts a set of singular channel backups, or a + * single encrypted multi-chan backup and attempts to recover any funds + * remaining within the channel. If we are able to unpack the backup, then the + * new channel will be shown under listchannels, as well as pending channels. + */ + restoreChannelBackups( + request?: DeepPartial + ): Promise; + /** + * SubscribeChannelBackups allows a client to sub-subscribe to the most up to + * date information concerning the state of all channel backups. Each time a + * new channel is added, we return the new set of channels, along with a + * multi-chan backup containing the backup info for all channels. Each time a + * channel is closed, we send a new update, which contains new new chan back + * ups, but the updated set of encrypted multi-chan backups with the closed + * channel(s) removed. + */ + subscribeChannelBackups( + request?: DeepPartial, + onMessage?: (msg: ChanBackupSnapshot) => void, + onError?: (err: Error) => void + ): void; + /** + * lncli: `bakemacaroon` + * BakeMacaroon allows the creation of a new macaroon with custom read and + * write permissions. No first-party caveats are added since this can be done + * offline. + */ + bakeMacaroon( + request?: DeepPartial + ): Promise; + /** + * lncli: `listmacaroonids` + * ListMacaroonIDs returns all root key IDs that are in use. + */ + listMacaroonIDs( + request?: DeepPartial + ): Promise; + /** + * lncli: `deletemacaroonid` + * DeleteMacaroonID deletes the specified macaroon ID and invalidates all + * macaroons derived from that ID. + */ + deleteMacaroonID( + request?: DeepPartial + ): Promise; + /** + * lncli: `listpermissions` + * ListPermissions lists all RPC method URIs and their required macaroon + * permissions to access them. + */ + listPermissions( + request?: DeepPartial + ): Promise; + /** + * CheckMacaroonPermissions checks whether a request follows the constraints + * imposed on the macaroon and that the macaroon is authorized to follow the + * provided permissions. + */ + checkMacaroonPermissions( + request?: DeepPartial + ): Promise; + /** + * RegisterRPCMiddleware adds a new gRPC middleware to the interceptor chain. A + * gRPC middleware is software component external to lnd that aims to add + * additional business logic to lnd by observing/intercepting/validating + * incoming gRPC client requests and (if needed) replacing/overwriting outgoing + * messages before they're sent to the client. When registering the middleware + * must identify itself and indicate what custom macaroon caveats it wants to + * be responsible for. Only requests that contain a macaroon with that specific + * custom caveat are then sent to the middleware for inspection. The other + * option is to register for the read-only mode in which all requests/responses + * are forwarded for interception to the middleware but the middleware is not + * allowed to modify any responses. As a security measure, _no_ middleware can + * modify responses for requests made with _unencumbered_ macaroons! + */ + registerRPCMiddleware( + request?: DeepPartial, + onMessage?: (msg: RPCMiddlewareRequest) => void, + onError?: (err: Error) => void + ): void; + /** + * lncli: `sendcustom` + * SendCustomMessage sends a custom peer message. + */ + sendCustomMessage( + request?: DeepPartial + ): Promise; + /** + * lncli: `subscribecustom` + * SubscribeCustomMessages subscribes to a stream of incoming custom peer + * messages. + * + * To include messages with type outside of the custom range (>= 32768) lnd + * needs to be compiled with the `dev` build tag, and the message type to + * override should be specified in lnd's experimental protocol configuration. + */ + subscribeCustomMessages( + request?: DeepPartial, + onMessage?: (msg: CustomMessage) => void, + onError?: (err: Error) => void + ): void; + /** + * lncli: `listaliases` + * ListAliases returns the set of all aliases that have ever existed with + * their confirmed SCID (if it exists) and/or the base SCID (in the case of + * zero conf). + */ + listAliases( + request?: DeepPartial + ): Promise; + /** + * LookupHtlcResolution retrieves a final htlc resolution from the database. + * If the htlc has no final resolution yet, a NotFound grpc status code is + * returned. + */ + lookupHtlcResolution( + request?: DeepPartial + ): Promise; +} + +type Builtin = + | Date + | Function + | Uint8Array + | string + | number + | boolean + | undefined; + +type DeepPartial = T extends Builtin + ? T + : T extends Array + ? Array> + : T extends ReadonlyArray + ? ReadonlyArray> + : T extends {} + ? { [K in keyof T]?: DeepPartial } + : Partial; diff --git a/lib/types/proto/tapd/mintrpc/mint.ts b/lib/types/proto/tapd/mintrpc/mint.ts index 597333d..2ba9762 100644 --- a/lib/types/proto/tapd/mintrpc/mint.ts +++ b/lib/types/proto/tapd/mintrpc/mint.ts @@ -1,5 +1,16 @@ /* eslint-disable */ -import type { AssetVersion, AssetType, AssetMeta } from '../taprootassets'; +import type { + AssetVersion, + AssetType, + AssetMeta, + KeyDescriptor, + ScriptKey, + GroupKeyRequest, + GroupVirtualTx, + TapscriptFullTree, + TapBranch, + GroupWitness +} from '../taprootassets'; export enum BatchState { BATCH_STATE_UNKNOWN = 'BATCH_STATE_UNKNOWN', @@ -36,13 +47,38 @@ export interface PendingAsset { * for future asset issuance. */ newGroupedAsset: boolean; - /** The specific group key this asset should be minted with. */ + /** The specific existing group key this asset should be minted with. */ groupKey: Uint8Array | string; /** * The name of the asset in the batch that will anchor a new asset group. * This asset will be minted with the same group key as the anchor asset. */ groupAnchor: string; + /** + * The optional key that will be used as the internal key for an asset group + * created with this asset. + */ + groupInternalKey: KeyDescriptor | undefined; + /** + * The optional root of a tapscript tree that will be used when constructing a + * new asset group key. This enables future issuance authorized with a script + * witness. + */ + groupTapscriptRoot: Uint8Array | string; + /** + * The optional script key to use for the new asset. If no script key is given, + * a BIP-86 key will be derived from the underlying wallet. + */ + scriptKey: ScriptKey | undefined; +} + +export interface UnsealedAsset { + /** The pending asset with an unsealed asset group. */ + asset: PendingAsset | undefined; + /** The group key request for the asset. */ + groupKeyRequest: GroupKeyRequest | undefined; + /** The group virtual transaction for the asset. */ + groupVirtualTx: GroupVirtualTx | undefined; } export interface MintAsset { @@ -72,13 +108,42 @@ export interface MintAsset { * an existing asset group. */ groupedAsset: boolean; - /** The specific group key this asset should be minted with. */ + /** The specific existing group key this asset should be minted with. */ groupKey: Uint8Array | string; /** * The name of the asset in the batch that will anchor a new asset group. * This asset will be minted with the same group key as the anchor asset. */ groupAnchor: string; + /** + * The optional key that will be used as the internal key for an asset group + * created with this asset. + */ + groupInternalKey: KeyDescriptor | undefined; + /** + * The optional root of a tapscript tree that will be used when constructing a + * new asset group key. This enables future issuance authorized with a script + * witness. + */ + groupTapscriptRoot: Uint8Array | string; + /** + * The optional script key to use for the new asset. If no script key is given, + * a BIP-86 key will be derived from the underlying wallet. + */ + scriptKey: ScriptKey | undefined; + /** + * Decimal display dictates the number of decimal places to shift the amount to + * the left converting from Taproot Asset integer representation to a + * UX-recognizable fractional quantity. + * + * For example, if the decimal_display value is 2 and there's 100 of those + * assets, then a wallet would display the amount as "1.00". This field is + * intended as information for wallets that display balances and has no impact + * on the behavior of the daemon or any other part of the protocol. This value + * is encoded in the MetaData field as a JSON field, therefore it is only + * compatible with assets that have a JSON MetaData field. + */ + decimalDisplay: number; } export interface MintAssetRequest { @@ -113,6 +178,61 @@ export interface MintingBatch { state: BatchState; /** The assets that are part of the batch. */ assets: PendingAsset[]; + /** The time the batch was created as a Unix timestamp (in seconds). */ + createdAt: string; + /** The current height of the block chain at the time of the batch creation. */ + heightHint: number; + /** + * The genesis transaction as a PSBT packet. Only populated if the batch has + * been committed. + */ + batchPsbt: Uint8Array | string; +} + +export interface VerboseBatch { + /** The minting batch, without any assets. */ + batch: MintingBatch | undefined; + /** The assets that are part of the batch. */ + unsealedAssets: UnsealedAsset[]; +} + +export interface FundBatchRequest { + /** + * If true, then the assets currently in the batch won't be returned in the + * response. This is mainly to avoid a lot of data being transmitted and + * possibly printed on the command line in the case of a very large batch. + */ + shortResponse: boolean; + /** The optional fee rate to use for the minting transaction, in sat/kw. */ + feeRate: number; + /** + * An ordered list of TapLeafs, which will be used to construct a + * Tapscript tree. + */ + fullTree: TapscriptFullTree | undefined; + /** A TapBranch that represents a Tapscript tree managed externally. */ + branch: TapBranch | undefined; +} + +export interface FundBatchResponse { + /** The funded batch. */ + batch: MintingBatch | undefined; +} + +export interface SealBatchRequest { + /** + * If true, then the assets currently in the batch won't be returned in the + * response. This is mainly to avoid a lot of data being transmitted and + * possibly printed on the command line in the case of a very large batch. + */ + shortResponse: boolean; + /** The assetID, witness pairs that authorize asset membership in a group. */ + groupWitnesses: GroupWitness[]; +} + +export interface SealBatchResponse { + /** The sealed batch. */ + batch: MintingBatch | undefined; } export interface FinalizeBatchRequest { @@ -124,6 +244,13 @@ export interface FinalizeBatchRequest { shortResponse: boolean; /** The optional fee rate to use for the minting transaction, in sat/kw. */ feeRate: number; + /** + * An ordered list of TapLeafs, which will be used to construct a + * Tapscript tree. + */ + fullTree: TapscriptFullTree | undefined; + /** A TapBranch that represents a Tapscript tree managed externally. */ + branch: TapBranch | undefined; } export interface FinalizeBatchResponse { @@ -149,10 +276,39 @@ export interface ListBatchRequest { * encoded string (use this for REST). */ batchKeyStr: string | undefined; + /** + * If true, pending asset group information will be shown for the pending + * batch. + */ + verbose: boolean; } export interface ListBatchResponse { - batches: MintingBatch[]; + batches: VerboseBatch[]; +} + +export interface SubscribeMintEventsRequest { + /** + * If true, then the assets currently in the batch won't be returned in the + * event's batch. This is mainly to avoid a lot of data being transmitted and + * possibly printed on the command line in the case of a very large batch. + */ + shortResponse: boolean; +} + +export interface MintEvent { + /** Execute timestamp (Unix timestamp in microseconds). */ + timestamp: string; + /** + * The last state of the batch that was successfully executed. If error + * below is set, then the batch_state is the state that lead to the error + * during its execution. + */ + batchState: BatchState; + /** The batch that the event is for. */ + batch: MintingBatch | undefined; + /** An optional error, indicating that executing the batch_state failed. */ + error: string; } export interface Mint { @@ -167,6 +323,28 @@ export interface Mint { mintAsset( request?: DeepPartial ): Promise; + /** + * tapcli `assets mint fund` + * FundBatch will attempt to fund the current pending batch with a genesis + * input, or create a new funded batch if no batch exists yet. This RPC is only + * needed if a custom witness is needed to finalize the batch. Otherwise, + * FinalizeBatch can be called directly. + */ + fundBatch( + request?: DeepPartial + ): Promise; + /** + * tapcli `assets mint seal` + * SealBatch will attempt to seal the current pending batch by creating and + * validating asset group witness for all assets in the batch. If a witness + * is not provided, a signature will be derived to serve as the witness. This + * RPC is only needed if any assets in the batch have a custom asset group key + * that require an external signer. Otherwise, FinalizeBatch can be called + * directly. + */ + sealBatch( + request?: DeepPartial + ): Promise; /** * tapcli: `assets mint finalize` * FinalizeBatch will attempt to finalize the current pending batch. @@ -189,6 +367,16 @@ export interface Mint { listBatches( request?: DeepPartial ): Promise; + /** + * tapcli: `events mint` + * SubscribeMintEvents allows a caller to subscribe to mint events for asset + * creation batches. + */ + subscribeMintEvents( + request?: DeepPartial, + onMessage?: (msg: MintEvent) => void, + onError?: (err: Error) => void + ): void; } type Builtin = diff --git a/lib/types/proto/tapd/priceoraclerpc/price_oracle.ts b/lib/types/proto/tapd/priceoraclerpc/price_oracle.ts new file mode 100644 index 0000000..f557795 --- /dev/null +++ b/lib/types/proto/tapd/priceoraclerpc/price_oracle.ts @@ -0,0 +1,189 @@ +/* eslint-disable */ +/** TransactionType is an enum representing the type of transaction. */ +export enum TransactionType { + /** PURCHASE - PURCHASE indicates a purchase transaction. */ + PURCHASE = 'PURCHASE', + /** SALE - SALE indicates a sale transaction. */ + SALE = 'SALE', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +/** + * FixedPoint is a scaled integer representation of a fractional number. + * + * This type consists of two integer fields: a coefficient and a scale. + * Using this format enables precise and consistent representation of fractional + * numbers while avoiding floating-point data types, which are prone to + * precision errors. + * + * The relationship between the fractional representation and its fixed-point + * representation is expressed as: + * ``` + * V = F_c / (10^F_s) + * ``` + * where: + * + * * `V` is the fractional value. + * + * * `F_c` is the coefficient component of the fixed-point representation. It is + * the scaled-up fractional value represented as an integer. + * + * * `F_s` is the scale component. It is an integer specifying how + * many decimal places `F_c` should be divided by to obtain the fractional + * representation. + */ +export interface FixedPoint { + /** + * The coefficient is the fractional value scaled-up as an integer. This + * integer is represented as a string as it may be too large to fit in a + * uint64. + */ + coefficient: string; + /** + * The scale is the component that determines how many decimal places + * the coefficient should be divided by to obtain the fractional value. + */ + scale: number; +} + +/** + * AssetRates represents the exchange rates for subject and payment assets + * relative to BTC, expressed as fixed-point numbers. It includes the rates + * for both assets and an expiration timestamp indicating when the rates + * are no longer valid. + */ +export interface AssetRates { + /** + * subjectAssetRate is the number of subject asset units per BTC represented + * as a fixed-point number. This field is also commonly referred to as the + * subject asset to BTC (conversion) rate. When the subject asset is BTC, + * this field should be set to 100 billion, as one BTC is equivalent to 100 + * billion msats. + */ + subjectAssetRate: FixedPoint | undefined; + /** + * paymentAssetRate is the number of payment asset units per BTC represented + * as a fixed-point number. This field is also commonly referred to as the + * payment asset to BTC (conversion) rate. When the payment asset is BTC, + * this field should be set to 100 billion, as one BTC is equivalent to 100 + * billion msats. + */ + paymentAssetRate: FixedPoint | undefined; + /** + * expiry_timestamp is the Unix timestamp in seconds after which the asset + * rates are no longer valid. + */ + expiryTimestamp: string; +} + +/** + * AssetSpecifier is a union type for specifying an asset by either its asset ID + * or group key. + */ +export interface AssetSpecifier { + /** The 32-byte asset ID specified as raw bytes (gRPC only). */ + assetId: Uint8Array | string | undefined; + /** The 32-byte asset ID encoded as a hex string (use this for REST). */ + assetIdStr: string | undefined; + /** The 32-byte asset group key specified as raw bytes (gRPC only). */ + groupKey: Uint8Array | string | undefined; + /** + * The 32-byte asset group key encoded as hex string (use this for + * REST). + */ + groupKeyStr: string | undefined; +} + +/** + * QueryAssetRatesRequest specifies the parameters for querying asset exchange + * rates in a transaction. It includes the transaction type, details about the + * subject and payment assets, and an optional hint for expected asset rates. + */ +export interface QueryAssetRatesRequest { + /** + * transaction_type indicates whether the transaction is a purchase or a + * sale. + */ + transactionType: TransactionType; + /** subject_asset is the asset to be priced for purchase or sale. */ + subjectAsset: AssetSpecifier | undefined; + /** + * subject_asset_max_amount is the maximum amount of the subject asset that + * could be involved in the transaction. + */ + subjectAssetMaxAmount: string; + /** + * payment_asset is the asset used for purchasing or receiving from a sale. + * + * NOTE: An asset ID of all zeros indicates that the payment asset is BTC. + * In this case, the asset rate will be given as milli-satoshi per asset + * unit + */ + paymentAsset: AssetSpecifier | undefined; + /** + * payment_asset_max_amount is the maximum amount of the payment asset that + * could be involved in the transaction. This field is optional. If set to + * zero, it is considered unset. + */ + paymentAssetMaxAmount: string; + /** + * asset_rates_hint is an optional suggestion of asset rates for the + * transaction, intended to provide guidance on expected pricing. + */ + assetRatesHint: AssetRates | undefined; +} + +/** + * QueryAssetRatesOkResponse is the successful response to a + * QueryAssetRates call. + */ +export interface QueryAssetRatesOkResponse { + /** asset_rates is the asset exchange rates for the transaction. */ + assetRates: AssetRates | undefined; +} + +/** QueryAssetRatesErrResponse is the error response to a QueryAssetRates call. */ +export interface QueryAssetRatesErrResponse { + /** error is the error message. */ + message: string; + /** code is the error code. */ + code: number; +} + +/** QueryAssetRatesResponse is the response from a QueryAssetRates RPC call. */ +export interface QueryAssetRatesResponse { + /** ok is the successful response to the query. */ + ok: QueryAssetRatesOkResponse | undefined; + /** error is the error response to the query. */ + error: QueryAssetRatesErrResponse | undefined; +} + +export interface PriceOracle { + /** + * QueryAssetRates retrieves the exchange rate between a tap asset and BTC for + * a specified transaction type, subject asset, and payment asset. The asset + * rate represents the number of tap asset units per BTC. + */ + queryAssetRates( + request?: DeepPartial + ): Promise; +} + +type Builtin = + | Date + | Function + | Uint8Array + | string + | number + | boolean + | undefined; + +type DeepPartial = T extends Builtin + ? T + : T extends Array + ? Array> + : T extends ReadonlyArray + ? ReadonlyArray> + : T extends {} + ? { [K in keyof T]?: DeepPartial } + : Partial; diff --git a/lib/types/proto/tapd/rfqrpc/rfq.ts b/lib/types/proto/tapd/rfqrpc/rfq.ts new file mode 100644 index 0000000..a43b0df --- /dev/null +++ b/lib/types/proto/tapd/rfqrpc/rfq.ts @@ -0,0 +1,405 @@ +/* eslint-disable */ + +/** QuoteRespStatus is an enum that represents the status of a quote response. */ +export enum QuoteRespStatus { + /** + * INVALID_ASSET_RATES - INVALID_ASSET_RATES indicates that at least one asset rate in the + * quote response is invalid. + */ + INVALID_ASSET_RATES = 'INVALID_ASSET_RATES', + /** + * INVALID_EXPIRY - INVALID_EXPIRY indicates that the expiry in the quote response is + * invalid. + */ + INVALID_EXPIRY = 'INVALID_EXPIRY', + /** + * PRICE_ORACLE_QUERY_ERR - PRICE_ORACLE_QUERY_ERR indicates that an error occurred when querying the + * price oracle whilst evaluating the quote response. + */ + PRICE_ORACLE_QUERY_ERR = 'PRICE_ORACLE_QUERY_ERR', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export interface AssetSpecifier { + /** The 32-byte asset ID specified as raw bytes (gRPC only). */ + assetId: Uint8Array | string | undefined; + /** The 32-byte asset ID encoded as a hex string (use this for REST). */ + assetIdStr: string | undefined; + /** The 32-byte asset group key specified as raw bytes (gRPC only). */ + groupKey: Uint8Array | string | undefined; + /** + * The 32-byte asset group key encoded as hex string (use this for + * REST). + */ + groupKeyStr: string | undefined; +} + +/** + * FixedPoint is a scaled integer representation of a fractional number. + * + * This type consists of two integer fields: a coefficient and a scale. + * Using this format enables precise and consistent representation of fractional + * numbers while avoiding floating-point data types, which are prone to + * precision errors. + * + * The relationship between the fractional representation and its fixed-point + * representation is expressed as: + * ``` + * V = F_c / (10^F_s) + * ``` + * where: + * + * * `V` is the fractional value. + * + * * `F_c` is the coefficient component of the fixed-point representation. It is + * the scaled-up fractional value represented as an integer. + * + * * `F_s` is the scale component. It is an integer specifying how + * many decimal places `F_c` should be divided by to obtain the fractional + * representation. + */ +export interface FixedPoint { + /** + * The coefficient is the fractional value scaled-up as an integer. This + * integer is represented as a string as it may be too large to fit in a + * uint64. + */ + coefficient: string; + /** + * The scale is the component that determines how many decimal places + * the coefficient should be divided by to obtain the fractional value. + */ + scale: number; +} + +export interface AddAssetBuyOrderRequest { + /** asset_specifier is the subject asset. */ + assetSpecifier: AssetSpecifier | undefined; + /** + * The maximum amount of the asset that the provider must be willing to + * offer. + */ + assetMaxAmt: string; + /** The unix timestamp in seconds after which the order is no longer valid. */ + expiry: string; + /** + * peer_pub_key is an optional field for specifying the public key of the + * intended recipient peer for the order. + */ + peerPubKey: Uint8Array | string; + /** + * timeout_seconds is the number of seconds to wait for the peer to respond + * with an accepted quote (or a rejection). + */ + timeoutSeconds: number; + /** + * If set, the check if a channel with the given asset exists with the peer + * will be skipped. An active channel with the peer is still required for + * the RFQ negotiation to work. This flag shouldn't be set outside of test + * scenarios. + */ + skipAssetChannelCheck: boolean; +} + +export interface AddAssetBuyOrderResponse { + /** + * accepted_quote holds the quote received from the peer as a response + * to our quote request. + */ + acceptedQuote: PeerAcceptedBuyQuote | undefined; + /** + * invalid_quote is returned if the quote response received from the + * peer was invalid or insufficient. + */ + invalidQuote: InvalidQuoteResponse | undefined; + /** + * rejected_quote is returned if the quote request was rejected by the + * peer. + */ + rejectedQuote: RejectedQuoteResponse | undefined; +} + +export interface AddAssetSellOrderRequest { + /** asset_specifier is the subject asset. */ + assetSpecifier: AssetSpecifier | undefined; + /** + * The maximum msat amount that the responding peer must agree to pay + * (units: millisats). + */ + paymentMaxAmt: string; + /** The unix timestamp in seconds after which the order is no longer valid. */ + expiry: string; + /** + * peer_pub_key is an optional field for specifying the public key of the + * intended recipient peer for the order. + */ + peerPubKey: Uint8Array | string; + /** + * timeout_seconds is the number of seconds to wait for the peer to respond + * with an accepted quote (or a rejection). + */ + timeoutSeconds: number; + /** + * If set, the check if a channel with the given asset exists with the peer + * will be skipped. An active channel with the peer is still required for + * the RFQ negotiation to work. This flag shouldn't be set outside of test + * scenarios. + */ + skipAssetChannelCheck: boolean; +} + +export interface AddAssetSellOrderResponse { + /** + * accepted_quote holds the quote received from the peer as a response + * to our quote request. + */ + acceptedQuote: PeerAcceptedSellQuote | undefined; + /** + * invalid_quote is returned if the quote response received from the + * peer was invalid or insufficient. + */ + invalidQuote: InvalidQuoteResponse | undefined; + /** + * rejected_quote is returned if the quote request was rejected by the + * peer. + */ + rejectedQuote: RejectedQuoteResponse | undefined; +} + +export interface AddAssetSellOfferRequest { + /** asset_specifier is the subject asset. */ + assetSpecifier: AssetSpecifier | undefined; + /** max_units is the maximum amount of the asset to sell. */ + maxUnits: string; +} + +export interface AddAssetSellOfferResponse {} + +export interface AddAssetBuyOfferRequest { + /** asset_specifier is the subject asset. */ + assetSpecifier: AssetSpecifier | undefined; + /** max_units is the maximum amount of the asset to buy. */ + maxUnits: string; +} + +export interface AddAssetBuyOfferResponse {} + +export interface QueryPeerAcceptedQuotesRequest {} + +export interface PeerAcceptedBuyQuote { + /** Quote counterparty peer. */ + peer: string; + /** The unique identifier of the quote request. */ + id: Uint8Array | string; + /** + * scid is the short channel ID of the channel over which the payment for + * the quote should be made. + */ + scid: string; + /** asset_amount is the amount of the subject asset. */ + assetAmount: string; + /** + * ask_asset_rate is the asset to BTC conversion rate represented as a + * fixed-point number. + */ + askAssetRate: FixedPoint | undefined; + /** The unix timestamp in seconds after which the quote is no longer valid. */ + expiry: string; +} + +export interface PeerAcceptedSellQuote { + /** Quote counterparty peer. */ + peer: string; + /** The unique identifier of the quote request. */ + id: Uint8Array | string; + /** + * scid is the short channel ID of the channel over which the payment for + * the quote should be made. + */ + scid: string; + /** asset_amount is the amount of the subject asset. */ + assetAmount: string; + /** + * bid_asset_rate is the asset to BTC conversion rate represented as a + * fixed-point number. + */ + bidAssetRate: FixedPoint | undefined; + /** The unix timestamp in seconds after which the quote is no longer valid. */ + expiry: string; +} + +/** + * InvalidQuoteResponse is a message that is returned when a quote response is + * invalid or insufficient. + */ +export interface InvalidQuoteResponse { + /** status is the status of the quote response. */ + status: QuoteRespStatus; + /** peer is the quote counterparty peer. */ + peer: string; + /** id is the unique identifier of the quote request. */ + id: Uint8Array | string; +} + +/** + * RejectedQuoteResponse is a message that is returned when a quote request is + * rejected by the peer. + */ +export interface RejectedQuoteResponse { + /** peer is the quote counterparty peer. */ + peer: string; + /** id is the unique identifier of the quote request. */ + id: Uint8Array | string; + /** error_message is a human-readable error message. */ + errorMessage: string; + /** error_code is a machine-readable error code. */ + errorCode: number; +} + +export interface QueryPeerAcceptedQuotesResponse { + /** + * buy_quotes is a list of asset buy quotes which were requested by our + * node and have been accepted by our peers. + */ + buyQuotes: PeerAcceptedBuyQuote[]; + /** + * sell_quotes is a list of asset sell quotes which were requested by our + * node and have been accepted by our peers. + */ + sellQuotes: PeerAcceptedSellQuote[]; +} + +export interface SubscribeRfqEventNtfnsRequest {} + +export interface PeerAcceptedBuyQuoteEvent { + /** Unix timestamp in microseconds. */ + timestamp: string; + /** The asset buy quote that was accepted by out peer. */ + peerAcceptedBuyQuote: PeerAcceptedBuyQuote | undefined; +} + +export interface PeerAcceptedSellQuoteEvent { + /** Unix timestamp in microseconds. */ + timestamp: string; + /** The asset sell quote that was accepted by out peer. */ + peerAcceptedSellQuote: PeerAcceptedSellQuote | undefined; +} + +export interface AcceptHtlcEvent { + /** Unix timestamp in microseconds. */ + timestamp: string; + /** + * scid is the short channel ID of the channel over which the payment for + * the quote is made. + */ + scid: string; +} + +export interface RfqEvent { + /** + * peer_accepted_buy_quote is an event that is emitted when a peer + * accepted (incoming) asset buy quote message is received. + */ + peerAcceptedBuyQuote: PeerAcceptedBuyQuoteEvent | undefined; + /** + * peer_accepted_sell_offer is an event that is emitted when a peer + * accepted (incoming) asset sell quote message is received. + */ + peerAcceptedSellQuote: PeerAcceptedSellQuoteEvent | undefined; + /** + * accept_htlc is an event that is sent when a HTLC is accepted by the + * RFQ service. + */ + acceptHtlc: AcceptHtlcEvent | undefined; +} + +export interface Rfq { + /** + * tapcli: `rfq buyorder` + * AddAssetBuyOrder is used to add a buy order for a specific asset. If a buy + * order already exists for the asset, it will be updated. + * + * A buy order instructs the RFQ (Request For Quote) system to request a quote + * from a peer for the acquisition of an asset. + * + * The normal use of a buy order is as follows: + * 1. Alice, operating a wallet node, wants to receive a Tap asset as payment + * by issuing a Lightning invoice. + * 2. Alice has an asset channel established with Bob's edge node. + * 3. Before issuing the invoice, Alice needs to agree on an exchange rate with + * Bob, who will facilitate the asset transfer. + * 4. To obtain the best exchange rate, Alice creates a buy order specifying + * the desired asset. + * 5. Alice's RFQ subsystem processes the buy order and sends buy requests to + * relevant peers to find the best rate. In this example, Bob is the only + * available peer. + * 6. Once Bob provides a satisfactory quote, Alice accepts it. + * 7. Alice issues the Lightning invoice, which Charlie will pay. + * 8. Instead of paying Alice directly, Charlie pays Bob. + * 9. Bob then forwards the agreed amount of the Tap asset to Alice over their + * asset channel. + */ + addAssetBuyOrder( + request?: DeepPartial + ): Promise; + /** + * tapcli: `rfq sellorder` + * AddAssetSellOrder is used to add a sell order for a specific asset. If a + * sell order already exists for the asset, it will be updated. + */ + addAssetSellOrder( + request?: DeepPartial + ): Promise; + /** + * tapcli: `rfq selloffer` + * AddAssetSellOffer is used to add a sell offer for a specific asset. If a + * sell offer already exists for the asset, it will be updated. + */ + addAssetSellOffer( + request?: DeepPartial + ): Promise; + /** + * tapcli: `rfq buyoffer` + * AddAssetBuyOffer is used to add a buy offer for a specific asset. If a + * buy offer already exists for the asset, it will be updated. + * + * A buy offer is used by the node to selectively accept or reject incoming + * asset sell quote requests before price is considered. + */ + addAssetBuyOffer( + request?: DeepPartial + ): Promise; + /** + * tapcli: `rfq acceptedquotes` + * QueryPeerAcceptedQuotes is used to query for quotes that were requested by + * our node and have been accepted our peers. + */ + queryPeerAcceptedQuotes( + request?: DeepPartial + ): Promise; + /** SubscribeRfqEventNtfns is used to subscribe to RFQ events. */ + subscribeRfqEventNtfns( + request?: DeepPartial, + onMessage?: (msg: RfqEvent) => void, + onError?: (err: Error) => void + ): void; +} + +type Builtin = + | Date + | Function + | Uint8Array + | string + | number + | boolean + | undefined; + +type DeepPartial = T extends Builtin + ? T + : T extends Array + ? Array> + : T extends ReadonlyArray + ? ReadonlyArray> + : T extends {} + ? { [K in keyof T]?: DeepPartial } + : Partial; diff --git a/lib/types/proto/tapd/routerrpc/router.ts b/lib/types/proto/tapd/routerrpc/router.ts new file mode 100644 index 0000000..9a1be56 --- /dev/null +++ b/lib/types/proto/tapd/routerrpc/router.ts @@ -0,0 +1,1070 @@ +/* eslint-disable */ +import type { + PaymentFailureReason, + Failure_FailureCode, + RouteHint, + FeatureBit, + Route, + Failure, + HTLCAttempt, + ChannelPoint, + AliasMap, + Payment +} from '../lightning'; + +export enum FailureDetail { + UNKNOWN = 'UNKNOWN', + NO_DETAIL = 'NO_DETAIL', + ONION_DECODE = 'ONION_DECODE', + LINK_NOT_ELIGIBLE = 'LINK_NOT_ELIGIBLE', + ON_CHAIN_TIMEOUT = 'ON_CHAIN_TIMEOUT', + HTLC_EXCEEDS_MAX = 'HTLC_EXCEEDS_MAX', + INSUFFICIENT_BALANCE = 'INSUFFICIENT_BALANCE', + INCOMPLETE_FORWARD = 'INCOMPLETE_FORWARD', + HTLC_ADD_FAILED = 'HTLC_ADD_FAILED', + FORWARDS_DISABLED = 'FORWARDS_DISABLED', + INVOICE_CANCELED = 'INVOICE_CANCELED', + INVOICE_UNDERPAID = 'INVOICE_UNDERPAID', + INVOICE_EXPIRY_TOO_SOON = 'INVOICE_EXPIRY_TOO_SOON', + INVOICE_NOT_OPEN = 'INVOICE_NOT_OPEN', + MPP_INVOICE_TIMEOUT = 'MPP_INVOICE_TIMEOUT', + ADDRESS_MISMATCH = 'ADDRESS_MISMATCH', + SET_TOTAL_MISMATCH = 'SET_TOTAL_MISMATCH', + SET_TOTAL_TOO_LOW = 'SET_TOTAL_TOO_LOW', + SET_OVERPAID = 'SET_OVERPAID', + UNKNOWN_INVOICE = 'UNKNOWN_INVOICE', + INVALID_KEYSEND = 'INVALID_KEYSEND', + MPP_IN_PROGRESS = 'MPP_IN_PROGRESS', + CIRCULAR_ROUTE = 'CIRCULAR_ROUTE', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export enum PaymentState { + /** IN_FLIGHT - Payment is still in flight. */ + IN_FLIGHT = 'IN_FLIGHT', + /** SUCCEEDED - Payment completed successfully. */ + SUCCEEDED = 'SUCCEEDED', + /** FAILED_TIMEOUT - There are more routes to try, but the payment timeout was exceeded. */ + FAILED_TIMEOUT = 'FAILED_TIMEOUT', + /** + * FAILED_NO_ROUTE - All possible routes were tried and failed permanently. Or were no + * routes to the destination at all. + */ + FAILED_NO_ROUTE = 'FAILED_NO_ROUTE', + /** FAILED_ERROR - A non-recoverable error has occurred. */ + FAILED_ERROR = 'FAILED_ERROR', + /** + * FAILED_INCORRECT_PAYMENT_DETAILS - Payment details incorrect (unknown hash, invalid amt or + * invalid final cltv delta) + */ + FAILED_INCORRECT_PAYMENT_DETAILS = 'FAILED_INCORRECT_PAYMENT_DETAILS', + /** FAILED_INSUFFICIENT_BALANCE - Insufficient local balance. */ + FAILED_INSUFFICIENT_BALANCE = 'FAILED_INSUFFICIENT_BALANCE', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export enum ResolveHoldForwardAction { + /** + * SETTLE - SETTLE is an action that is used to settle an HTLC instead of forwarding + * it. + */ + SETTLE = 'SETTLE', + /** FAIL - FAIL is an action that is used to fail an HTLC backwards. */ + FAIL = 'FAIL', + /** RESUME - RESUME is an action that is used to resume a forward HTLC. */ + RESUME = 'RESUME', + /** + * RESUME_MODIFIED - RESUME_MODIFIED is an action that is used to resume a hold forward HTLC + * with modifications specified during interception. + */ + RESUME_MODIFIED = 'RESUME_MODIFIED', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export enum ChanStatusAction { + ENABLE = 'ENABLE', + DISABLE = 'DISABLE', + AUTO = 'AUTO', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export interface SendPaymentRequest { + /** The identity pubkey of the payment recipient */ + dest: Uint8Array | string; + /** + * Number of satoshis to send. + * + * The fields amt and amt_msat are mutually exclusive. + */ + amt: string; + /** The hash to use within the payment's HTLC */ + paymentHash: Uint8Array | string; + /** + * The CLTV delta from the current height that should be used to set the + * timelock for the final hop. + */ + finalCltvDelta: number; + /** + * A bare-bones invoice for a payment within the Lightning Network. With the + * details of the invoice, the sender has all the data necessary to send a + * payment to the recipient. The amount in the payment request may be zero. In + * that case it is required to set the amt field as well. If no payment request + * is specified, the following fields are required: dest, amt and payment_hash. + */ + paymentRequest: string; + /** + * An upper limit on the amount of time we should spend when attempting to + * fulfill the payment. This is expressed in seconds. If we cannot make a + * successful payment within this time frame, an error will be returned. + * This field must be non-zero. + */ + timeoutSeconds: number; + /** + * The maximum number of satoshis that will be paid as a fee of the payment. + * If this field is left to the default value of 0, only zero-fee routes will + * be considered. This usually means single hop routes connecting directly to + * the destination. To send the payment without a fee limit, use max int here. + * + * The fields fee_limit_sat and fee_limit_msat are mutually exclusive. + */ + feeLimitSat: string; + /** + * Deprecated, use outgoing_chan_ids. The channel id of the channel that must + * be taken to the first hop. If zero, any channel may be used (unless + * outgoing_chan_ids are set). + * + * @deprecated + */ + outgoingChanId: string; + /** + * An optional maximum total time lock for the route. This should not + * exceed lnd's `--max-cltv-expiry` setting. If zero, then the value of + * `--max-cltv-expiry` is enforced. + */ + cltvLimit: number; + /** Optional route hints to reach the destination through private channels. */ + routeHints: RouteHint[]; + /** + * An optional field that can be used to pass an arbitrary set of TLV records + * to a peer which understands the new records. This can be used to pass + * application specific data during the payment attempt. Record types are + * required to be in the custom range >= 65536. When using REST, the values + * must be encoded as base64. + */ + destCustomRecords: { [key: string]: Uint8Array | string }; + /** + * Number of millisatoshis to send. + * + * The fields amt and amt_msat are mutually exclusive. + */ + amtMsat: string; + /** + * The maximum number of millisatoshis that will be paid as a fee of the + * payment. If this field is left to the default value of 0, only zero-fee + * routes will be considered. This usually means single hop routes connecting + * directly to the destination. To send the payment without a fee limit, use + * max int here. + * + * The fields fee_limit_sat and fee_limit_msat are mutually exclusive. + */ + feeLimitMsat: string; + /** The pubkey of the last hop of the route. If empty, any hop may be used. */ + lastHopPubkey: Uint8Array | string; + /** If set, circular payments to self are permitted. */ + allowSelfPayment: boolean; + /** + * Features assumed to be supported by the final node. All transitive feature + * dependencies must also be set properly. For a given feature bit pair, either + * optional or remote may be set, but not both. If this field is nil or empty, + * the router will try to load destination features from the graph as a + * fallback. + */ + destFeatures: FeatureBit[]; + /** + * The maximum number of partial payments that may be use to complete the full + * amount. + */ + maxParts: number; + /** + * If set, only the final payment update is streamed back. Intermediate updates + * that show which htlcs are still in flight are suppressed. + */ + noInflightUpdates: boolean; + /** + * The channel ids of the channels are allowed for the first hop. If empty, + * any channel may be used. + */ + outgoingChanIds: string[]; + /** + * An optional payment addr to be included within the last hop of the route. + * This is also called payment secret in specifications (e.g. BOLT 11). + */ + paymentAddr: Uint8Array | string; + /** + * The largest payment split that should be attempted when making a payment if + * splitting is necessary. Setting this value will effectively cause lnd to + * split more aggressively, vs only when it thinks it needs to. Note that this + * value is in milli-satoshis. + */ + maxShardSizeMsat: string; + /** If set, an AMP-payment will be attempted. */ + amp: boolean; + /** + * The time preference for this payment. Set to -1 to optimize for fees + * only, to 1 to optimize for reliability only or a value inbetween for a mix. + */ + timePref: number; + /** + * If set, the payment loop can be interrupted by manually canceling the + * payment context, even before the payment timeout is reached. Note that the + * payment may still succeed after cancellation, as in-flight attempts can + * still settle afterwards. Canceling will only prevent further attempts from + * being sent. + */ + cancelable: boolean; + /** + * An optional field that can be used to pass an arbitrary set of TLV records + * to the first hop peer of this payment. This can be used to pass application + * specific data during the payment attempt. Record types are required to be in + * the custom range >= 65536. When using REST, the values must be encoded as + * base64. + */ + firstHopCustomRecords: { [key: string]: Uint8Array | string }; +} + +export interface SendPaymentRequest_DestCustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + +export interface SendPaymentRequest_FirstHopCustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + +export interface TrackPaymentRequest { + /** The hash of the payment to look up. */ + paymentHash: Uint8Array | string; + /** + * If set, only the final payment update is streamed back. Intermediate updates + * that show which htlcs are still in flight are suppressed. + */ + noInflightUpdates: boolean; +} + +export interface TrackPaymentsRequest { + /** + * If set, only the final payment updates are streamed back. Intermediate + * updates that show which htlcs are still in flight are suppressed. + */ + noInflightUpdates: boolean; +} + +export interface RouteFeeRequest { + /** + * The destination one wishes to obtain a routing fee quote to. If set, this + * parameter requires the amt_sat parameter also to be set. This parameter + * combination triggers a graph based routing fee estimation as opposed to a + * payment probe based estimate in case a payment request is provided. The + * graph based estimation is an algorithm that is executed on the in memory + * graph. Hence its runtime is significantly shorter than a payment probe + * estimation that sends out actual payments to the network. + */ + dest: Uint8Array | string; + /** + * The amount one wishes to send to the target destination. It is only to be + * used in combination with the dest parameter. + */ + amtSat: string; + /** + * A payment request of the target node that the route fee request is intended + * for. Its parameters are input to probe payments that estimate routing fees. + * The timeout parameter can be specified to set a maximum time on the probing + * attempt. Cannot be used in combination with dest and amt_sat. + */ + paymentRequest: string; + /** + * A user preference of how long a probe payment should maximally be allowed to + * take, denoted in seconds. The probing payment loop is aborted if this + * timeout is reached. Note that the probing process itself can take longer + * than the timeout if the HTLC becomes delayed or stuck. Canceling the context + * of this call will not cancel the payment loop, the duration is only + * controlled by the timeout parameter. + */ + timeout: number; +} + +export interface RouteFeeResponse { + /** + * A lower bound of the estimated fee to the target destination within the + * network, expressed in milli-satoshis. + */ + routingFeeMsat: string; + /** + * An estimate of the worst case time delay that can occur. Note that callers + * will still need to factor in the final CLTV delta of the last hop into this + * value. + */ + timeLockDelay: string; + /** + * An indication whether a probing payment succeeded or whether and why it + * failed. FAILURE_REASON_NONE indicates success. + */ + failureReason: PaymentFailureReason; +} + +export interface SendToRouteRequest { + /** The payment hash to use for the HTLC. */ + paymentHash: Uint8Array | string; + /** Route that should be used to attempt to complete the payment. */ + route: Route | undefined; + /** + * Whether the payment should be marked as failed when a temporary error is + * returned from the given route. Set it to true so the payment won't be + * failed unless a terminal error is occurred, such as payment timeout, no + * routes, incorrect payment details, or insufficient funds. + */ + skipTempErr: boolean; + /** + * An optional field that can be used to pass an arbitrary set of TLV records + * to the first hop peer of this payment. This can be used to pass application + * specific data during the payment attempt. Record types are required to be in + * the custom range >= 65536. When using REST, the values must be encoded as + * base64. + */ + firstHopCustomRecords: { [key: string]: Uint8Array | string }; +} + +export interface SendToRouteRequest_FirstHopCustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + +export interface SendToRouteResponse { + /** The preimage obtained by making the payment. */ + preimage: Uint8Array | string; + /** The failure message in case the payment failed. */ + failure: Failure | undefined; +} + +export interface ResetMissionControlRequest {} + +export interface ResetMissionControlResponse {} + +export interface QueryMissionControlRequest {} + +/** QueryMissionControlResponse contains mission control state. */ +export interface QueryMissionControlResponse { + /** Node pair-level mission control state. */ + pairs: PairHistory[]; +} + +export interface XImportMissionControlRequest { + /** Node pair-level mission control state to be imported. */ + pairs: PairHistory[]; + /** + * Whether to force override MC pair history. Note that even with force + * override the failure pair is imported before the success pair and both + * still clamp existing failure/success amounts. + */ + force: boolean; +} + +export interface XImportMissionControlResponse {} + +/** PairHistory contains the mission control state for a particular node pair. */ +export interface PairHistory { + /** The source node pubkey of the pair. */ + nodeFrom: Uint8Array | string; + /** The destination node pubkey of the pair. */ + nodeTo: Uint8Array | string; + history: PairData | undefined; +} + +export interface PairData { + /** Time of last failure. */ + failTime: string; + /** + * Lowest amount that failed to forward rounded to whole sats. This may be + * set to zero if the failure is independent of amount. + */ + failAmtSat: string; + /** + * Lowest amount that failed to forward in millisats. This may be + * set to zero if the failure is independent of amount. + */ + failAmtMsat: string; + /** Time of last success. */ + successTime: string; + /** Highest amount that we could successfully forward rounded to whole sats. */ + successAmtSat: string; + /** Highest amount that we could successfully forward in millisats. */ + successAmtMsat: string; +} + +export interface GetMissionControlConfigRequest {} + +export interface GetMissionControlConfigResponse { + /** Mission control's currently active config. */ + config: MissionControlConfig | undefined; +} + +export interface SetMissionControlConfigRequest { + /** + * The config to set for mission control. Note that all values *must* be set, + * because the full config will be applied. + */ + config: MissionControlConfig | undefined; +} + +export interface SetMissionControlConfigResponse {} + +export interface MissionControlConfig { + /** + * Deprecated, use AprioriParameters. The amount of time mission control will + * take to restore a penalized node or channel back to 50% success probability, + * expressed in seconds. Setting this value to a higher value will penalize + * failures for longer, making mission control less likely to route through + * nodes and channels that we have previously recorded failures for. + * + * @deprecated + */ + halfLifeSeconds: string; + /** + * Deprecated, use AprioriParameters. The probability of success mission + * control should assign to hop in a route where it has no other information + * available. Higher values will make mission control more willing to try hops + * that we have no information about, lower values will discourage trying these + * hops. + * + * @deprecated + */ + hopProbability: number; + /** + * Deprecated, use AprioriParameters. The importance that mission control + * should place on historical results, expressed as a value in [0;1]. Setting + * this value to 1 will ignore all historical payments and just use the hop + * probability to assess the probability of success for each hop. A zero value + * ignores hop probability completely and relies entirely on historical + * results, unless none are available. + * + * @deprecated + */ + weight: number; + /** The maximum number of payment results that mission control will store. */ + maximumPaymentResults: number; + /** + * The minimum time that must have passed since the previously recorded failure + * before we raise the failure amount. + */ + minimumFailureRelaxInterval: string; + /** + * ProbabilityModel defines which probability estimator should be used in + * pathfinding. Note that the bimodal estimator is experimental. + */ + model: MissionControlConfig_ProbabilityModel; + apriori: AprioriParameters | undefined; + bimodal: BimodalParameters | undefined; +} + +export enum MissionControlConfig_ProbabilityModel { + APRIORI = 'APRIORI', + BIMODAL = 'BIMODAL', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export interface BimodalParameters { + /** + * NodeWeight defines how strongly other previous forwardings on channels of a + * router should be taken into account when computing a channel's probability + * to route. The allowed values are in the range [0, 1], where a value of 0 + * means that only direct information about a channel is taken into account. + */ + nodeWeight: number; + /** + * ScaleMsat describes the scale over which channels statistically have some + * liquidity left. The value determines how quickly the bimodal distribution + * drops off from the edges of a channel. A larger value (compared to typical + * channel capacities) means that the drop off is slow and that channel + * balances are distributed more uniformly. A small value leads to the + * assumption of very unbalanced channels. + */ + scaleMsat: string; + /** + * DecayTime describes the information decay of knowledge about previous + * successes and failures in channels. The smaller the decay time, the quicker + * we forget about past forwardings. + */ + decayTime: string; +} + +export interface AprioriParameters { + /** + * The amount of time mission control will take to restore a penalized node + * or channel back to 50% success probability, expressed in seconds. Setting + * this value to a higher value will penalize failures for longer, making + * mission control less likely to route through nodes and channels that we + * have previously recorded failures for. + */ + halfLifeSeconds: string; + /** + * The probability of success mission control should assign to hop in a route + * where it has no other information available. Higher values will make mission + * control more willing to try hops that we have no information about, lower + * values will discourage trying these hops. + */ + hopProbability: number; + /** + * The importance that mission control should place on historical results, + * expressed as a value in [0;1]. Setting this value to 1 will ignore all + * historical payments and just use the hop probability to assess the + * probability of success for each hop. A zero value ignores hop probability + * completely and relies entirely on historical results, unless none are + * available. + */ + weight: number; + /** + * The fraction of a channel's capacity that we consider to have liquidity. For + * amounts that come close to or exceed the fraction, an additional penalty is + * applied. A value of 1.0 disables the capacity factor. Allowed values are in + * [0.75, 1.0]. + */ + capacityFraction: number; +} + +export interface QueryProbabilityRequest { + /** The source node pubkey of the pair. */ + fromNode: Uint8Array | string; + /** The destination node pubkey of the pair. */ + toNode: Uint8Array | string; + /** The amount for which to calculate a probability. */ + amtMsat: string; +} + +export interface QueryProbabilityResponse { + /** The success probability for the requested pair. */ + probability: number; + /** The historical data for the requested pair. */ + history: PairData | undefined; +} + +export interface BuildRouteRequest { + /** + * The amount to send expressed in msat. If set to zero, the minimum routable + * amount is used. + */ + amtMsat: string; + /** + * CLTV delta from the current height that should be used for the timelock + * of the final hop + */ + finalCltvDelta: number; + /** + * The channel id of the channel that must be taken to the first hop. If zero, + * any channel may be used. + */ + outgoingChanId: string; + /** + * A list of hops that defines the route. This does not include the source hop + * pubkey. + */ + hopPubkeys: Uint8Array | string[]; + /** + * An optional payment addr to be included within the last hop of the route. + * This is also called payment secret in specifications (e.g. BOLT 11). + */ + paymentAddr: Uint8Array | string; + /** + * An optional field that can be used to pass an arbitrary set of TLV records + * to the first hop peer of this payment. This can be used to pass application + * specific data during the payment attempt. Record types are required to be in + * the custom range >= 65536. When using REST, the values must be encoded as + * base64. + */ + firstHopCustomRecords: { [key: string]: Uint8Array | string }; +} + +export interface BuildRouteRequest_FirstHopCustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + +export interface BuildRouteResponse { + /** Fully specified route that can be used to execute the payment. */ + route: Route | undefined; +} + +export interface SubscribeHtlcEventsRequest {} + +/** + * HtlcEvent contains the htlc event that was processed. These are served on a + * best-effort basis; events are not persisted, delivery is not guaranteed + * (in the event of a crash in the switch, forward events may be lost) and + * some events may be replayed upon restart. Events consumed from this package + * should be de-duplicated by the htlc's unique combination of incoming and + * outgoing channel id and htlc id. [EXPERIMENTAL] + */ +export interface HtlcEvent { + /** + * The short channel id that the incoming htlc arrived at our node on. This + * value is zero for sends. + */ + incomingChannelId: string; + /** + * The short channel id that the outgoing htlc left our node on. This value + * is zero for receives. + */ + outgoingChannelId: string; + /** + * Incoming id is the index of the incoming htlc in the incoming channel. + * This value is zero for sends. + */ + incomingHtlcId: string; + /** + * Outgoing id is the index of the outgoing htlc in the outgoing channel. + * This value is zero for receives. + */ + outgoingHtlcId: string; + /** The time in unix nanoseconds that the event occurred. */ + timestampNs: string; + /** + * The event type indicates whether the htlc was part of a send, receive or + * forward. + */ + eventType: HtlcEvent_EventType; + forwardEvent: ForwardEvent | undefined; + forwardFailEvent: ForwardFailEvent | undefined; + settleEvent: SettleEvent | undefined; + linkFailEvent: LinkFailEvent | undefined; + subscribedEvent: SubscribedEvent | undefined; + finalHtlcEvent: FinalHtlcEvent | undefined; +} + +export enum HtlcEvent_EventType { + UNKNOWN = 'UNKNOWN', + SEND = 'SEND', + RECEIVE = 'RECEIVE', + FORWARD = 'FORWARD', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export interface HtlcInfo { + /** The timelock on the incoming htlc. */ + incomingTimelock: number; + /** The timelock on the outgoing htlc. */ + outgoingTimelock: number; + /** The amount of the incoming htlc. */ + incomingAmtMsat: string; + /** The amount of the outgoing htlc. */ + outgoingAmtMsat: string; +} + +export interface ForwardEvent { + /** Info contains details about the htlc that was forwarded. */ + info: HtlcInfo | undefined; +} + +export interface ForwardFailEvent {} + +export interface SettleEvent { + /** The revealed preimage. */ + preimage: Uint8Array | string; +} + +export interface FinalHtlcEvent { + settled: boolean; + offchain: boolean; +} + +export interface SubscribedEvent {} + +export interface LinkFailEvent { + /** Info contains details about the htlc that we failed. */ + info: HtlcInfo | undefined; + /** FailureCode is the BOLT error code for the failure. */ + wireFailure: Failure_FailureCode; + /** + * FailureDetail provides additional information about the reason for the + * failure. This detail enriches the information provided by the wire message + * and may be 'no detail' if the wire message requires no additional metadata. + */ + failureDetail: FailureDetail; + /** A string representation of the link failure. */ + failureString: string; +} + +export interface PaymentStatus { + /** Current state the payment is in. */ + state: PaymentState; + /** The pre-image of the payment when state is SUCCEEDED. */ + preimage: Uint8Array | string; + /** The HTLCs made in attempt to settle the payment [EXPERIMENTAL]. */ + htlcs: HTLCAttempt[]; +} + +export interface CircuitKey { + /** / The id of the channel that the is part of this circuit. */ + chanId: string; + /** / The index of the incoming htlc in the incoming channel. */ + htlcId: string; +} + +export interface ForwardHtlcInterceptRequest { + /** + * The key of this forwarded htlc. It defines the incoming channel id and + * the index in this channel. + */ + incomingCircuitKey: CircuitKey | undefined; + /** The incoming htlc amount. */ + incomingAmountMsat: string; + /** The incoming htlc expiry. */ + incomingExpiry: number; + /** + * The htlc payment hash. This value is not guaranteed to be unique per + * request. + */ + paymentHash: Uint8Array | string; + /** + * The requested outgoing channel id for this forwarded htlc. Because of + * non-strict forwarding, this isn't necessarily the channel over which the + * packet will be forwarded eventually. A different channel to the same peer + * may be selected as well. + */ + outgoingRequestedChanId: string; + /** The outgoing htlc amount. */ + outgoingAmountMsat: string; + /** The outgoing htlc expiry. */ + outgoingExpiry: number; + /** Any custom records that were present in the payload. */ + customRecords: { [key: string]: Uint8Array | string }; + /** The onion blob for the next hop */ + onionBlob: Uint8Array | string; + /** + * The block height at which this htlc will be auto-failed to prevent the + * channel from force-closing. + */ + autoFailHeight: number; + /** The custom records of the peer's incoming p2p wire message. */ + inWireCustomRecords: { [key: string]: Uint8Array | string }; +} + +export interface ForwardHtlcInterceptRequest_CustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + +export interface ForwardHtlcInterceptRequest_InWireCustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + +/** + * ForwardHtlcInterceptResponse enables the caller to resolve a previously hold + * forward. The caller can choose either to: + * - `Resume`: Execute the default behavior (usually forward). + * - `ResumeModified`: Execute the default behavior (usually forward) with HTLC + * field modifications. + * - `Reject`: Fail the htlc backwards. + * - `Settle`: Settle this htlc with a given preimage. + */ +export interface ForwardHtlcInterceptResponse { + /** + * The key of this forwarded htlc. It defines the incoming channel id and + * the index in this channel. + */ + incomingCircuitKey: CircuitKey | undefined; + /** The resolve action for this intercepted htlc. */ + action: ResolveHoldForwardAction; + /** The preimage in case the resolve action is Settle. */ + preimage: Uint8Array | string; + /** + * Encrypted failure message in case the resolve action is Fail. + * + * If failure_message is specified, the failure_code field must be set + * to zero. + */ + failureMessage: Uint8Array | string; + /** + * Return the specified failure code in case the resolve action is Fail. The + * message data fields are populated automatically. + * + * If a non-zero failure_code is specified, failure_message must not be set. + * + * For backwards-compatibility reasons, TEMPORARY_CHANNEL_FAILURE is the + * default value for this field. + */ + failureCode: Failure_FailureCode; + /** + * The amount that was set on the p2p wire message of the incoming HTLC. + * This field is ignored if the action is not RESUME_MODIFIED or the amount + * is zero. + */ + inAmountMsat: string; + /** + * The amount to set on the p2p wire message of the resumed HTLC. This field + * is ignored if the action is not RESUME_MODIFIED or the amount is zero. + */ + outAmountMsat: string; + /** + * Any custom records that should be set on the p2p wire message message of + * the resumed HTLC. This field is ignored if the action is not + * RESUME_MODIFIED. + */ + outWireCustomRecords: { [key: string]: Uint8Array | string }; +} + +export interface ForwardHtlcInterceptResponse_OutWireCustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + +export interface UpdateChanStatusRequest { + chanPoint: ChannelPoint | undefined; + action: ChanStatusAction; +} + +export interface UpdateChanStatusResponse {} + +export interface AddAliasesRequest { + aliasMaps: AliasMap[]; +} + +export interface AddAliasesResponse { + aliasMaps: AliasMap[]; +} + +export interface DeleteAliasesRequest { + aliasMaps: AliasMap[]; +} + +export interface DeleteAliasesResponse { + aliasMaps: AliasMap[]; +} + +/** + * Router is a service that offers advanced interaction with the router + * subsystem of the daemon. + */ +export interface Router { + /** + * SendPaymentV2 attempts to route a payment described by the passed + * PaymentRequest to the final destination. The call returns a stream of + * payment updates. When using this RPC, make sure to set a fee limit, as the + * default routing fee limit is 0 sats. Without a non-zero fee limit only + * routes without fees will be attempted which often fails with + * FAILURE_REASON_NO_ROUTE. + */ + sendPaymentV2( + request?: DeepPartial, + onMessage?: (msg: Payment) => void, + onError?: (err: Error) => void + ): void; + /** + * lncli: `trackpayment` + * TrackPaymentV2 returns an update stream for the payment identified by the + * payment hash. + */ + trackPaymentV2( + request?: DeepPartial, + onMessage?: (msg: Payment) => void, + onError?: (err: Error) => void + ): void; + /** + * TrackPayments returns an update stream for every payment that is not in a + * terminal state. Note that if payments are in-flight while starting a new + * subscription, the start of the payment stream could produce out-of-order + * and/or duplicate events. In order to get updates for every in-flight + * payment attempt make sure to subscribe to this method before initiating any + * payments. + */ + trackPayments( + request?: DeepPartial, + onMessage?: (msg: Payment) => void, + onError?: (err: Error) => void + ): void; + /** + * EstimateRouteFee allows callers to obtain a lower bound w.r.t how much it + * may cost to send an HTLC to the target end destination. + */ + estimateRouteFee( + request?: DeepPartial + ): Promise; + /** + * Deprecated, use SendToRouteV2. SendToRoute attempts to make a payment via + * the specified route. This method differs from SendPayment in that it + * allows users to specify a full route manually. This can be used for + * things like rebalancing, and atomic swaps. It differs from the newer + * SendToRouteV2 in that it doesn't return the full HTLC information. + * + * @deprecated + */ + sendToRoute( + request?: DeepPartial + ): Promise; + /** + * SendToRouteV2 attempts to make a payment via the specified route. This + * method differs from SendPayment in that it allows users to specify a full + * route manually. This can be used for things like rebalancing, and atomic + * swaps. + */ + sendToRouteV2( + request?: DeepPartial + ): Promise; + /** + * lncli: `resetmc` + * ResetMissionControl clears all mission control state and starts with a clean + * slate. + */ + resetMissionControl( + request?: DeepPartial + ): Promise; + /** + * lncli: `querymc` + * QueryMissionControl exposes the internal mission control state to callers. + * It is a development feature. + */ + queryMissionControl( + request?: DeepPartial + ): Promise; + /** + * lncli: `importmc` + * XImportMissionControl is an experimental API that imports the state provided + * to the internal mission control's state, using all results which are more + * recent than our existing values. These values will only be imported + * in-memory, and will not be persisted across restarts. + */ + xImportMissionControl( + request?: DeepPartial + ): Promise; + /** + * lncli: `getmccfg` + * GetMissionControlConfig returns mission control's current config. + */ + getMissionControlConfig( + request?: DeepPartial + ): Promise; + /** + * lncli: `setmccfg` + * SetMissionControlConfig will set mission control's config, if the config + * provided is valid. + */ + setMissionControlConfig( + request?: DeepPartial + ): Promise; + /** + * lncli: `queryprob` + * Deprecated. QueryProbability returns the current success probability + * estimate for a given node pair and amount. The call returns a zero success + * probability if no channel is available or if the amount violates min/max + * HTLC constraints. + */ + queryProbability( + request?: DeepPartial + ): Promise; + /** + * lncli: `buildroute` + * BuildRoute builds a fully specified route based on a list of hop public + * keys. It retrieves the relevant channel policies from the graph in order to + * calculate the correct fees and time locks. + * Note that LND will use its default final_cltv_delta if no value is supplied. + * Make sure to add the correct final_cltv_delta depending on the invoice + * restriction. Moreover the caller has to make sure to provide the + * payment_addr if the route is paying an invoice which signaled it. + */ + buildRoute( + request?: DeepPartial + ): Promise; + /** + * SubscribeHtlcEvents creates a uni-directional stream from the server to + * the client which delivers a stream of htlc events. + */ + subscribeHtlcEvents( + request?: DeepPartial, + onMessage?: (msg: HtlcEvent) => void, + onError?: (err: Error) => void + ): void; + /** + * Deprecated, use SendPaymentV2. SendPayment attempts to route a payment + * described by the passed PaymentRequest to the final destination. The call + * returns a stream of payment status updates. + * + * @deprecated + */ + sendPayment( + request?: DeepPartial, + onMessage?: (msg: PaymentStatus) => void, + onError?: (err: Error) => void + ): void; + /** + * Deprecated, use TrackPaymentV2. TrackPayment returns an update stream for + * the payment identified by the payment hash. + * + * @deprecated + */ + trackPayment( + request?: DeepPartial, + onMessage?: (msg: PaymentStatus) => void, + onError?: (err: Error) => void + ): void; + /** + * HtlcInterceptor dispatches a bi-directional streaming RPC in which + * Forwarded HTLC requests are sent to the client and the client responds with + * a boolean that tells LND if this htlc should be intercepted. + * In case of interception, the htlc can be either settled, cancelled or + * resumed later by using the ResolveHoldForward endpoint. + */ + htlcInterceptor( + request?: DeepPartial, + onMessage?: (msg: ForwardHtlcInterceptRequest) => void, + onError?: (err: Error) => void + ): void; + /** + * lncli: `updatechanstatus` + * UpdateChanStatus attempts to manually set the state of a channel + * (enabled, disabled, or auto). A manual "disable" request will cause the + * channel to stay disabled until a subsequent manual request of either + * "enable" or "auto". + */ + updateChanStatus( + request?: DeepPartial + ): Promise; + /** + * XAddLocalChanAliases is an experimental API that creates a set of new + * channel SCID alias mappings. The final total set of aliases in the manager + * after the add operation is returned. This is only a locally stored alias, + * and will not be communicated to the channel peer via any message. Therefore, + * routing over such an alias will only work if the peer also calls this same + * RPC on their end. If an alias already exists, an error is returned + */ + xAddLocalChanAliases( + request?: DeepPartial + ): Promise; + /** + * XDeleteLocalChanAliases is an experimental API that deletes a set of alias + * mappings. The final total set of aliases in the manager after the delete + * operation is returned. The deletion will not be communicated to the channel + * peer via any message. + */ + xDeleteLocalChanAliases( + request?: DeepPartial + ): Promise; +} + +type Builtin = + | Date + | Function + | Uint8Array + | string + | number + | boolean + | undefined; + +type DeepPartial = T extends Builtin + ? T + : T extends Array + ? Array> + : T extends ReadonlyArray + ? ReadonlyArray> + : T extends {} + ? { [K in keyof T]?: DeepPartial } + : Partial; diff --git a/lib/types/proto/tapd/tapchannelrpc/tapchannel.ts b/lib/types/proto/tapd/tapchannelrpc/tapchannel.ts new file mode 100644 index 0000000..1cce0d9 --- /dev/null +++ b/lib/types/proto/tapd/tapchannelrpc/tapchannel.ts @@ -0,0 +1,230 @@ +/* eslint-disable */ +import type { SendPaymentRequest as SendPaymentRequest1 } from '../routerrpc/router'; +import type { + PeerAcceptedSellQuote, + PeerAcceptedBuyQuote +} from '../rfqrpc/rfq'; +import type { + Payment, + Invoice, + AddInvoiceResponse as AddInvoiceResponse2 +} from '../lightning'; + +export interface FundChannelRequest { + /** + * The asset amount to fund the channel with. The BTC amount is fixed and + * cannot be customized (for now). + */ + assetAmount: string; + /** The asset ID to use for the channel funding. */ + assetId: Uint8Array | string; + /** + * The public key of the peer to open the channel with. Must already be + * connected to this peer. + */ + peerPubkey: Uint8Array | string; + /** The channel funding fee rate in sat/vByte. */ + feeRateSatPerVbyte: number; + /** + * The number of satoshis to give the remote side as part of the initial + * commitment state. This is equivalent to first opening a channel and then + * sending the remote party funds, but all done in one step. Therefore, this + * is equivalent to a donation to the remote party, unless they reimburse + * the funds in another way (outside the protocol). + */ + pushSat: string; +} + +export interface FundChannelResponse { + /** The channel funding transaction ID. */ + txid: string; + /** The index of the channel funding output in the funding transaction. */ + outputIndex: number; +} + +export interface RouterSendPaymentData { + /** + * The string encoded asset ID to amount mapping. Instructs the router to + * use these assets in the given amounts for the payment. Can be empty for + * a payment of an invoice, if the RFQ ID is set instead. + */ + assetAmounts: { [key: string]: string }; + /** + * The RFQ ID to use for the payment. Can be empty for a direct keysend + * payment that doesn't involve any conversion (and thus no RFQ). + */ + rfqId: Uint8Array | string; +} + +export interface RouterSendPaymentData_AssetAmountsEntry { + key: string; + value: string; +} + +export interface EncodeCustomRecordsRequest { + routerSendPayment: RouterSendPaymentData | undefined; +} + +export interface EncodeCustomRecordsResponse { + /** The encoded custom records in TLV format. */ + customRecords: { [key: string]: Uint8Array | string }; +} + +export interface EncodeCustomRecordsResponse_CustomRecordsEntry { + key: string; + value: Uint8Array | string; +} + +export interface SendPaymentRequest { + /** + * The asset ID to use for the payment. This must be set for both invoice + * and keysend payments, unless RFQ negotiation was already done beforehand + * and payment_request.first_hop_custom_records already contains valid RFQ + * data. + */ + assetId: Uint8Array | string; + /** + * The asset amount to send in a keysend payment. This amount is ignored for + * invoice payments as the asset amount is negotiated through RFQ with the + * peer, depending on the invoice amount. This can also be left unset if RFQ + * negotiation was already done beforehand and + * payment_request.first_hop_custom_records already contains valid RFQ data. + */ + assetAmount: string; + /** + * The node identity public key of the peer to ask for a quote for sending + * out the assets and converting them to satoshis. This must be specified if + * there are multiple channels with the given asset ID. + */ + peerPubkey: Uint8Array | string; + /** + * The full lnd payment request to send. All fields behave the same way as + * they do for lnd's routerrpc.SendPaymentV2 RPC method (see the API docs + * at https://lightning.engineering/api-docs/api/lnd/router/send-payment-v2 + * for more details). + * To send a keysend payment, the payment_request.dest_custom_records must + * contain a valid keysend record (key 5482373484 and a 32-byte preimage + * that corresponds to the payment hash). + */ + paymentRequest: SendPaymentRequest1 | undefined; + /** + * The rfq id to use for this payment. If the user sets this value then the + * payment will immediately be dispatched, skipping the rfq negotiation + * phase, and using the following rfq id instead. + */ + rfqId: Uint8Array | string; +} + +export interface SendPaymentResponse { + /** + * In case channel assets need to be swapped to another asset, an asset + * sell order is negotiated with the channel peer. The result will be + * the first message in the response stream. If no swap is needed, the + * payment results will be streamed directly. + */ + acceptedSellOrder: PeerAcceptedSellQuote | undefined; + /** + * The payment result of a single payment attempt. Multiple attempts may + * be returned per payment request until either the payment succeeds or + * the payment times out. + */ + paymentResult: Payment | undefined; +} + +export interface HodlInvoice { + paymentHash: Uint8Array | string; +} + +export interface AddInvoiceRequest { + /** The asset ID to use for the invoice. */ + assetId: Uint8Array | string; + /** The asset amount to receive. */ + assetAmount: string; + /** + * The node identity public key of the peer to ask for a quote for receiving + * assets and converting them from satoshis. This must be specified if + * there are multiple channels with the given asset ID. + */ + peerPubkey: Uint8Array | string; + /** + * The full lnd invoice request to send. All fields (except for the value + * and the route hints) behave the same way as they do for lnd's + * lnrpc.AddInvoice RPC method (see the API docs at + * https://lightning.engineering/api-docs/api/lnd/lightning/add-invoice + * for more details). The value/value_msat fields will be overwritten by the + * satoshi (or milli-satoshi) equivalent of the asset amount, after + * negotiating a quote with a peer that supports the given asset ID. + */ + invoiceRequest: Invoice | undefined; + /** + * If set, then this will make the invoice created a hodl invoice, which + * won't be settled automatically. Instead, users will need to use the + * invoicesrpc.SettleInvoice call to manually settle the invoice. + */ + hodlInvoice: HodlInvoice | undefined; +} + +export interface AddInvoiceResponse { + /** The quote for the purchase of assets that was accepted by the peer. */ + acceptedBuyQuote: PeerAcceptedBuyQuote | undefined; + /** The result of the invoice creation. */ + invoiceResult: AddInvoiceResponse2 | undefined; +} + +export interface TaprootAssetChannels { + /** + * FundChannel initiates the channel funding negotiation with a peer for the + * creation of a channel that contains a specified amount of a given asset. + */ + fundChannel( + request?: DeepPartial + ): Promise; + /** + * EncodeCustomRecords allows RPC users to encode Taproot Asset channel related + * data into the TLV format that is used in the custom records of the lnd + * payment or other channel related RPCs. This RPC is completely stateless and + * does not perform any checks on the data provided, other than pure format + * validation. + */ + encodeCustomRecords( + request?: DeepPartial + ): Promise; + /** + * SendPayment is a wrapper around lnd's routerrpc.SendPaymentV2 RPC method + * with asset specific parameters. It allows RPC users to send asset keysend + * payments (direct payments) or payments to an invoice with a specified asset + * amount. + */ + sendPayment( + request?: DeepPartial, + onMessage?: (msg: SendPaymentResponse) => void, + onError?: (err: Error) => void + ): void; + /** + * AddInvoice is a wrapper around lnd's lnrpc.AddInvoice method with asset + * specific parameters. It allows RPC users to create invoices that correspond + * to the specified asset amount. + */ + addInvoice( + request?: DeepPartial + ): Promise; +} + +type Builtin = + | Date + | Function + | Uint8Array + | string + | number + | boolean + | undefined; + +type DeepPartial = T extends Builtin + ? T + : T extends Array + ? Array> + : T extends ReadonlyArray + ? ReadonlyArray> + : T extends {} + ? { [K in keyof T]?: DeepPartial } + : Partial; diff --git a/lib/types/proto/tapd/tapdevrpc/tapdev.ts b/lib/types/proto/tapd/tapdevrpc/tapdev.ts new file mode 100644 index 0000000..a37db99 --- /dev/null +++ b/lib/types/proto/tapd/tapdevrpc/tapdev.ts @@ -0,0 +1,133 @@ +/* eslint-disable */ +import type { Addr } from '../taprootassets'; + +/** + * ProofTransferType is the type of proof transfer attempt. The transfer is + * either a proof delivery to the transfer counterparty or receiving a proof + * from the transfer counterparty. Note that the transfer counterparty is + * usually the proof courier service. + */ +export enum ProofTransferType { + /** + * PROOF_TRANSFER_TYPE_SEND - This value indicates that the proof transfer attempt is a delivery to the + * transfer counterparty. + */ + PROOF_TRANSFER_TYPE_SEND = 'PROOF_TRANSFER_TYPE_SEND', + /** + * PROOF_TRANSFER_TYPE_RECEIVE - This value indicates that the proof transfer attempt is a receive from + * the transfer counterparty. + */ + PROOF_TRANSFER_TYPE_RECEIVE = 'PROOF_TRANSFER_TYPE_RECEIVE', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export interface ImportProofRequest { + proofFile: Uint8Array | string; + genesisPoint: string; +} + +export interface ImportProofResponse {} + +export interface SubscribeSendAssetEventNtfnsRequest {} + +export interface SendAssetEvent { + /** An event which indicates that a send state is about to be executed. */ + executeSendStateEvent: ExecuteSendStateEvent | undefined; + /** + * An event which indicates that the proof transfer backoff wait period + * will start imminently. + */ + proofTransferBackoffWaitEvent: ProofTransferBackoffWaitEvent | undefined; +} + +export interface ExecuteSendStateEvent { + /** Execute timestamp (microseconds). */ + timestamp: string; + /** The send state that is about to be executed. */ + sendState: string; +} + +export interface ProofTransferBackoffWaitEvent { + /** Transfer attempt timestamp (microseconds). */ + timestamp: string; + /** Backoff is the active backoff wait duration. */ + backoff: string; + /** + * Tries counter is the number of tries we've made so far during the + * course of the current backoff procedure to deliver the proof to the + * receiver. + */ + triesCounter: string; + /** The type of proof transfer attempt. */ + transferType: ProofTransferType; +} + +export interface SubscribeReceiveAssetEventNtfnsRequest {} + +export interface AssetReceiveCompleteEvent { + /** Event creation timestamp. */ + timestamp: string; + /** The address that received the asset. */ + address: Addr | undefined; + /** The outpoint of the transaction that was used to receive the asset. */ + outpoint: string; +} + +export interface ReceiveAssetEvent { + /** + * An event which indicates that the proof transfer backoff wait period + * will start imminently. + */ + proofTransferBackoffWaitEvent: ProofTransferBackoffWaitEvent | undefined; + /** An event which indicates that an asset receive process has finished. */ + assetReceiveCompleteEvent: AssetReceiveCompleteEvent | undefined; +} + +export interface TapDev { + /** + * tapcli: `dev importproof` + * ImportProof attempts to import a proof file into the daemon. If successful, + * a new asset will be inserted on disk, spendable using the specified target + * script key, and internal key. + */ + importProof( + request?: DeepPartial + ): Promise; + /** + * SubscribeSendAssetEventNtfns registers a subscription to the event + * notification stream which relates to the asset sending process. + */ + subscribeSendAssetEventNtfns( + request?: DeepPartial, + onMessage?: (msg: SendAssetEvent) => void, + onError?: (err: Error) => void + ): void; + /** + * SubscribeReceiveAssetEventNtfns registers a subscription to the event + * notification stream which relates to the asset receive process. + */ + subscribeReceiveAssetEventNtfns( + request?: DeepPartial, + onMessage?: (msg: ReceiveAssetEvent) => void, + onError?: (err: Error) => void + ): void; +} + +type Builtin = + | Date + | Function + | Uint8Array + | string + | number + | boolean + | undefined; + +type DeepPartial = T extends Builtin + ? T + : T extends Array + ? Array> + : T extends ReadonlyArray + ? ReadonlyArray> + : T extends {} + ? { [K in keyof T]?: DeepPartial } + : Partial; diff --git a/lib/types/proto/tapd/taprootassets.ts b/lib/types/proto/tapd/taprootassets.ts index 410877b..660b1f8 100644 --- a/lib/types/proto/tapd/taprootassets.ts +++ b/lib/types/proto/tapd/taprootassets.ts @@ -22,6 +22,11 @@ export enum AssetMetaType { * should be interpreted as opaque blobs. */ META_TYPE_OPAQUE = 'META_TYPE_OPAQUE', + /** + * META_TYPE_JSON - JSON is used for asset meta blobs that are to be interpreted as valid JSON + * strings. + */ + META_TYPE_JSON = 'META_TYPE_JSON', UNRECOGNIZED = 'UNRECOGNIZED' } @@ -52,28 +57,40 @@ export enum OutputType { * output. In either case, the asset of this output has a tx witness. */ OUTPUT_TYPE_SPLIT_ROOT = 'OUTPUT_TYPE_SPLIT_ROOT', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +/** + * ProofDeliveryStatus is an enum that describes the status of the delivery of + * a proof associated with an asset transfer output. + */ +export enum ProofDeliveryStatus { + /** PROOF_DELIVERY_STATUS_NOT_APPLICABLE - Delivery is not applicable; the proof will not be delivered. */ + PROOF_DELIVERY_STATUS_NOT_APPLICABLE = 'PROOF_DELIVERY_STATUS_NOT_APPLICABLE', + /** PROOF_DELIVERY_STATUS_COMPLETE - The proof has been successfully delivered. */ + PROOF_DELIVERY_STATUS_COMPLETE = 'PROOF_DELIVERY_STATUS_COMPLETE', /** - * OUTPUT_TYPE_PASSIVE_ASSETS_ONLY - OUTPUT_TYPE_PASSIVE_ASSETS_ONLY indicates that this output only carries - * passive assets and therefore the asset in this output is nil. The passive - * assets themselves are signed in their own virtual transactions and - * are not present in this packet. + * PROOF_DELIVERY_STATUS_PENDING - The proof is pending delivery. This status indicates that the proof has + * not yet been delivered successfully. One or more attempts at proof + * delivery may have been made. */ - OUTPUT_TYPE_PASSIVE_ASSETS_ONLY = 'OUTPUT_TYPE_PASSIVE_ASSETS_ONLY', + PROOF_DELIVERY_STATUS_PENDING = 'PROOF_DELIVERY_STATUS_PENDING', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export enum AddrVersion { /** - * OUTPUT_TYPE_PASSIVE_SPLIT_ROOT - OUTPUT_TYPE_PASSIVE_SPLIT_ROOT is a split root output that carries the - * change from a split or a tombstone from a non-interactive full value send - * output, as well as passive assets. + * ADDR_VERSION_UNSPECIFIED - ADDR_VERSION_UNSPECIFIED is the default value for an address version in + * an RPC message. It is unmarshalled to the latest address version. */ - OUTPUT_TYPE_PASSIVE_SPLIT_ROOT = 'OUTPUT_TYPE_PASSIVE_SPLIT_ROOT', + ADDR_VERSION_UNSPECIFIED = 'ADDR_VERSION_UNSPECIFIED', + /** ADDR_VERSION_V0 - ADDR_VERSION_V0 is the initial address version. */ + ADDR_VERSION_V0 = 'ADDR_VERSION_V0', /** - * OUTPUT_TYPE_SIMPLE_PASSIVE_ASSETS - OUTPUT_TYPE_SIMPLE_PASSIVE_ASSETS is a plain full-value interactive send - * output that also carries passive assets. This is a special case where we - * send the full value of a single asset in a commitment to a new script - * key, but also carry passive assets in the same output. This is useful for - * key rotation (send-to-self) scenarios or asset burns where we burn the - * full supply of a single asset within a commitment. + * ADDR_VERSION_V1 - ADDR_VERSION_V1 is the address version that uses V2 Taproot Asset + * commitments. */ - OUTPUT_TYPE_SIMPLE_PASSIVE_ASSETS = 'OUTPUT_TYPE_SIMPLE_PASSIVE_ASSETS', + ADDR_VERSION_V1 = 'ADDR_VERSION_V1', UNRECOGNIZED = 'UNRECOGNIZED' } @@ -86,23 +103,69 @@ export enum AddrEventStatus { UNRECOGNIZED = 'UNRECOGNIZED' } -/** - * ProofTransferType is the type of proof transfer attempt. The transfer is - * either a proof delivery to the transfer counterparty or receiving a proof - * from the transfer counterparty. Note that the transfer counterparty is - * usually the proof courier service. - */ -export enum ProofTransferType { +export enum SendState { + /** + * SEND_STATE_VIRTUAL_INPUT_SELECT - Input coin selection to pick out which asset inputs should be spent is + * executed during this state. + */ + SEND_STATE_VIRTUAL_INPUT_SELECT = 'SEND_STATE_VIRTUAL_INPUT_SELECT', + /** SEND_STATE_VIRTUAL_SIGN - The virtual transaction is signed during this state. */ + SEND_STATE_VIRTUAL_SIGN = 'SEND_STATE_VIRTUAL_SIGN', + /** SEND_STATE_ANCHOR_SIGN - The Bitcoin anchor transaction is signed during this state. */ + SEND_STATE_ANCHOR_SIGN = 'SEND_STATE_ANCHOR_SIGN', + /** + * SEND_STATE_LOG_COMMITMENT - The outbound packet is written to the database during this state, + * including the partial proof suffixes. Only parcels that complete this + * state can be resumed on restart. + */ + SEND_STATE_LOG_COMMITMENT = 'SEND_STATE_LOG_COMMITMENT', + /** + * SEND_STATE_BROADCAST - The Bitcoin anchor transaction is broadcast to the network during this + * state. + */ + SEND_STATE_BROADCAST = 'SEND_STATE_BROADCAST', + /** + * SEND_STATE_WAIT_CONFIRMATION - The on-chain anchor transaction needs to reach at least 1 confirmation. + * This state waits for the confirmation. + */ + SEND_STATE_WAIT_CONFIRMATION = 'SEND_STATE_WAIT_CONFIRMATION', + /** + * SEND_STATE_STORE_PROOFS - The anchor transaction was confirmed in a block and the full proofs can + * now be constructed during this stage. + */ + SEND_STATE_STORE_PROOFS = 'SEND_STATE_STORE_PROOFS', + /** + * SEND_STATE_TRANSFER_PROOFS - The full proofs are sent to the recipient(s) with the proof courier + * service during this state. + */ + SEND_STATE_TRANSFER_PROOFS = 'SEND_STATE_TRANSFER_PROOFS', + /** SEND_STATE_COMPLETED - The send state machine has completed the send process. */ + SEND_STATE_COMPLETED = 'SEND_STATE_COMPLETED', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export enum ParcelType { + /** PARCEL_TYPE_ADDRESS - The parcel is an address parcel. */ + PARCEL_TYPE_ADDRESS = 'PARCEL_TYPE_ADDRESS', + /** + * PARCEL_TYPE_PRE_SIGNED - The parcel type is a pre-signed parcel where the virtual transactions are + * signed outside of the send state machine. Parcels of this type will only + * get send states starting from SEND_STATE_ANCHOR_SIGN. + */ + PARCEL_TYPE_PRE_SIGNED = 'PARCEL_TYPE_PRE_SIGNED', /** - * PROOF_TRANSFER_TYPE_SEND - This value indicates that the proof transfer attempt is a delivery to the - * transfer counterparty. + * PARCEL_TYPE_PENDING - The parcel is pending and was resumed on the latest restart of the + * daemon. The original parcel type (address or pre-signed) is not known + * anymore, as it's not relevant for the remaining steps. Parcels of this + * type will only get send states starting from SEND_STATE_BROADCAST. */ - PROOF_TRANSFER_TYPE_SEND = 'PROOF_TRANSFER_TYPE_SEND', + PARCEL_TYPE_PENDING = 'PARCEL_TYPE_PENDING', /** - * PROOF_TRANSFER_TYPE_RECEIVE - This value indicates that the proof transfer attempt is a receive from - * the transfer counterparty. + * PARCEL_TYPE_PRE_ANCHORED - The parcel type is a pre-anchored parcel where the full anchor + * transaction and all proofs are already available. Parcels of this type + * will only get send states starting from SEND_STATE_LOG_COMMITMENT. */ - PROOF_TRANSFER_TYPE_RECEIVE = 'PROOF_TRANSFER_TYPE_RECEIVE', + PARCEL_TYPE_PRE_ANCHORED = 'PARCEL_TYPE_PRE_ANCHORED', UNRECOGNIZED = 'UNRECOGNIZED' } @@ -126,6 +189,14 @@ export interface ListAssetRequest { withWitness: boolean; includeSpent: boolean; includeLeased: boolean; + /** + * List assets that aren't confirmed yet. Only freshly minted assets will + * show in the asset list with a block height of 0. All other forms of + * unconfirmed assets will not appear in the list until the transaction is + * confirmed (check either transfers or receives for unconfirmed outbound or + * inbound assets). + */ + includeUnconfirmedMints: boolean; } export interface AnchorInfo { @@ -172,8 +243,71 @@ export interface GenesisInfo { * the genesis transaction. */ outputIndex: number; - /** The version of the Taproot Asset commitment that created this asset. */ - version: number; +} + +export interface GroupKeyRequest { + /** The internal key for the asset group before any tweaks have been applied. */ + rawKey: KeyDescriptor | undefined; + /** + * The genesis of the group anchor asset, which is used to derive the single + * tweak for the group key. For a new group key, this will be the genesis of + * new_asset. + */ + anchorGenesis: GenesisInfo | undefined; + /** + * The optional root of a tapscript tree that will be used when constructing a + * new asset group key. This enables future issuance authorized with a script + * witness. + */ + tapscriptRoot: Uint8Array | string; + /** + * The serialized asset which we are requesting group membership for. A + * successful request will produce a witness that authorizes this asset to be a + * member of this asset group. + */ + newAsset: Uint8Array | string; +} + +export interface TxOut { + /** The value of the output being spent. */ + value: string; + /** The script of the output being spent. */ + pkScript: Uint8Array | string; +} + +export interface GroupVirtualTx { + /** + * The virtual transaction that represents the genesis state transition of a + * grouped asset. + */ + transaction: Uint8Array | string; + /** + * The transaction output that represents a grouped asset. The tweaked + * group key is set as the PkScript of this output. This is used in combination + * with Tx to produce an asset group witness. + */ + prevOut: TxOut | undefined; + /** + * The asset ID of the grouped asset in a GroupKeyRequest. This ID is + * needed to construct a sign descriptor, as it is the single tweak for the + * group internal key. + */ + genesisId: Uint8Array | string; + /** + * The tweaked group key for a specific GroupKeyRequest. This is used to + * construct a complete group key after producing an asset group witness. + */ + tweakedKey: Uint8Array | string; +} + +export interface GroupWitness { + /** + * The asset ID of the pending asset that should be assigned this asset + * group witness. + */ + genesisId: Uint8Array | string; + /** The serialized witness stack for the asset group. */ + witness: Uint8Array | string[]; } export interface AssetGroup { @@ -189,6 +323,11 @@ export interface AssetGroup { * specified by the above key. */ assetWitness: Uint8Array | string; + /** + * The root hash of a tapscript tree, which enables future issuance authorized + * with a script witness. + */ + tapscriptRoot: Uint8Array | string; } export interface GroupKeyReveal { @@ -203,6 +342,22 @@ export interface GenesisReveal { genesisBaseReveal: GenesisInfo | undefined; } +export interface DecimalDisplay { + /** + * Decimal display dictates the number of decimal places to shift the amount to + * the left converting from Taproot Asset integer representation to a + * UX-recognizable fractional quantity. + * + * For example, if the decimal_display value is 2 and there's 100 of those + * assets, then a wallet would display the amount as "1.00". This field is + * intended as information for wallets that display balances and has no impact + * on the behavior of the daemon or any other part of the protocol. This value + * is encoded in the MetaData field as a JSON field, therefore it is only + * compatible with assets that have a JSON MetaData field. + */ + decimalDisplay: number; +} + export interface Asset { /** The version of the Taproot Asset. */ version: AssetVersion; @@ -245,6 +400,32 @@ export interface Asset { * assets in this output are destroyed and can no longer be spent. */ isBurn: boolean; + /** + * Indicates whether this script key has either been derived by the local + * wallet or was explicitly declared to be known by using the + * DeclareScriptKey RPC. Knowing the key conceptually means the key belongs + * to the local wallet or is at least known by a software that operates on + * the local wallet. The flag is never serialized in proofs, so this is + * never explicitly set for keys foreign to the local wallet. Therefore, if + * this method returns true for a script key, it means the asset with the + * script key will be shown in the wallet balance. + */ + scriptKeyDeclaredKnown: boolean; + /** + * Indicates whether the script key is known to have a Tapscript spend path, + * meaning that the Taproot merkle root tweak is not empty. This will only + * ever be true if either script_key_is_local or script_key_internals_known + * is true as well, since the presence of a Tapscript spend path cannot be + * determined for script keys that aren't known to the wallet of the local + * tapd node. + */ + scriptKeyHasScriptPath: boolean; + /** + * This field defines a decimal display value that may be present. If this + * field is null, it means the presence of a decimal display field is + * unknown in the current context. + */ + decimalDisplay: DecimalDisplay | undefined; } export interface PrevWitness { @@ -259,6 +440,17 @@ export interface SplitCommitment { export interface ListAssetResponse { assets: Asset[]; + /** + * This is a count of unconfirmed outgoing transfers. Unconfirmed transfers + * do not appear as assets in this endpoint response. + */ + unconfirmedTransfers: string; + /** + * This is a count of freshly minted assets that haven't been confirmed on + * chain yet. These assets will appear in the asset list with a block height + * of 0 if include_unconfirmed_mints is set to true in the request. + */ + unconfirmedMints: string; } export interface ListUtxosRequest { @@ -282,6 +474,13 @@ export interface ManagedUtxo { merkleRoot: Uint8Array | string; /** The assets held at this UTXO. */ assets: Asset[]; + /** The lease owner for this UTXO. If blank the UTXO isn't leased. */ + leaseOwner: Uint8Array | string; + /** + * The expiry time as a unix time stamp for this lease. If blank the utxo + * isn't leased. + */ + leaseExpiryUnix: string; } export interface ListUtxosResponse { @@ -346,6 +545,8 @@ export interface ListBalancesRequest { * asset group. */ groupKeyFilter: Uint8Array | string; + /** An option to include previous leased assets in the balances. */ + includeLeased: boolean; } export interface AssetBalance { @@ -377,13 +578,47 @@ export interface ListBalancesResponse_AssetGroupBalancesEntry { value: AssetGroupBalance | undefined; } -export interface ListTransfersRequest {} +export interface ListTransfersRequest { + /** + * anchor_txid specifies the hexadecimal encoded txid string of the anchor + * transaction for which to retrieve transfers. An empty value indicates + * that this parameter should be disregarded in transfer selection. + */ + anchorTxid: string; +} export interface ListTransfersResponse { /** The unordered list of outgoing asset transfers. */ transfers: AssetTransfer[]; } +/** + * ChainHash represents a hash value, typically a double SHA-256 of some data. + * Common examples include block hashes and transaction hashes. + * + * This versatile message type is used in various Bitcoin-related messages and + * structures, providing two different formats of the same hash to accommodate + * both developer and user needs. + */ +export interface ChainHash { + /** + * The raw hash value in byte format. + * + * This format is optimized for programmatic use, particularly for Go + * developers, enabling easy integration with other RPC calls or binary + * operations. + */ + hash: Uint8Array | string; + /** + * The byte-reversed hash value as a hexadecimal string. + * + * This format is intended for human interaction, making it easy to copy, + * paste, and use in contexts like command-line arguments or configuration + * files. + */ + hashStr: string; +} + export interface AssetTransfer { transferTimestamp: string; /** @@ -397,6 +632,12 @@ export interface AssetTransfer { inputs: TransferInput[]; /** Describes the set of newly created asset outputs. */ outputs: TransferOutput[]; + /** + * The block hash of the blockchain block that contains the anchor + * transaction. If this value is unset, the anchor transaction is + * unconfirmed. + */ + anchorTxBlockHash: ChainHash | undefined; } export interface TransferInput { @@ -440,6 +681,10 @@ export interface TransferOutput { splitCommitRootHash: Uint8Array | string; outputType: OutputType; assetVersion: AssetVersion; + lockTime: string; + relativeLockTime: string; + /** The delivery status of the proof associated with this output. */ + proofDeliveryStatus: ProofDeliveryStatus; } export interface StopRequest {} @@ -491,6 +736,8 @@ export interface Addr { proofCourierAddr: string; /** The asset version of the address. */ assetVersion: AssetVersion; + /** The version of the address. */ + addressVersion: AddrVersion; } export interface QueryAddrRequest { @@ -549,6 +796,8 @@ export interface NewAddrRequest { proofCourierAddr: string; /** The asset version to use when sending/receiving to/from this address. */ assetVersion: AssetVersion; + /** The version of this address. */ + addressVersion: AddrVersion; } export interface ScriptKey { @@ -581,6 +830,23 @@ export interface KeyDescriptor { keyLoc: KeyLocator | undefined; } +export interface TapscriptFullTree { + /** The complete, ordered list of all tap leaves of the tree. */ + allLeaves: TapLeaf[]; +} + +export interface TapLeaf { + /** The script of the tap leaf. */ + script: Uint8Array | string; +} + +export interface TapBranch { + /** The TapHash of the left child of the root hash of a Tapscript tree. */ + leftTaphash: Uint8Array | string; + /** The TapHash of the right child of the root hash of a Tapscript tree. */ + rightTaphash: Uint8Array | string; +} + export interface DecodeAddrRequest { addr: string; } @@ -767,61 +1033,6 @@ export interface GetInfoResponse { syncToChain: boolean; } -export interface SubscribeSendAssetEventNtfnsRequest {} - -export interface SendAssetEvent { - /** An event which indicates that a send state is about to be executed. */ - executeSendStateEvent: ExecuteSendStateEvent | undefined; - /** - * An event which indicates that the proof transfer backoff wait period - * will start imminently. - */ - proofTransferBackoffWaitEvent: ProofTransferBackoffWaitEvent | undefined; -} - -export interface ExecuteSendStateEvent { - /** Execute timestamp (microseconds). */ - timestamp: string; - /** The send state that is about to be executed. */ - sendState: string; -} - -export interface ProofTransferBackoffWaitEvent { - /** Transfer attempt timestamp (microseconds). */ - timestamp: string; - /** Backoff is the active backoff wait duration. */ - backoff: string; - /** - * Tries counter is the number of tries we've made so far during the - * course of the current backoff procedure to deliver the proof to the - * receiver. - */ - triesCounter: string; - /** The type of proof transfer attempt. */ - transferType: ProofTransferType; -} - -export interface SubscribeReceiveAssetEventNtfnsRequest {} - -export interface AssetReceiveCompleteEvent { - /** Event creation timestamp. */ - timestamp: string; - /** The address that received the asset. */ - address: Addr | undefined; - /** The outpoint of the transaction that was used to receive the asset. */ - outpoint: string; -} - -export interface ReceiveAssetEvent { - /** - * An event which indicates that the proof transfer backoff wait period - * will start imminently. - */ - proofTransferBackoffWaitEvent: ProofTransferBackoffWaitEvent | undefined; - /** An event which indicates that an asset receive process has finished. */ - assetReceiveCompleteEvent: AssetReceiveCompleteEvent | undefined; -} - export interface FetchAssetMetaRequest { /** The asset ID of the asset to fetch the meta for. */ assetId: Uint8Array | string | undefined; @@ -845,6 +1056,8 @@ export interface BurnAssetRequest { * for the burn to succeed. */ confirmationText: string; + /** A note that may contain user defined metadata related to this burn. */ + note: string; } export interface BurnAssetResponse { @@ -854,6 +1067,32 @@ export interface BurnAssetResponse { burnProof: DecodedProof | undefined; } +export interface ListBurnsRequest { + /** The asset id of the burnt asset. */ + assetId: Uint8Array | string; + /** The tweaked group key of the group this asset belongs to. */ + tweakedGroupKey: Uint8Array | string; + /** The txid of the transaction that the burn was anchored to. */ + anchorTxid: Uint8Array | string; +} + +export interface AssetBurn { + /** A note that may contain user defined metadata related to this burn. */ + note: string; + /** The asset id of the burnt asset. */ + assetId: Uint8Array | string; + /** The tweaked group key of the group this asset belongs to. */ + tweakedGroupKey: Uint8Array | string; + /** The amount of burnt assets. */ + amount: string; + /** The txid of the transaction that the burn was anchored to. */ + anchorTxid: Uint8Array | string; +} + +export interface ListBurnsResponse { + burns: AssetBurn[]; +} + export interface OutPoint { /** Raw bytes representing the transaction id. */ txid: Uint8Array | string; @@ -861,6 +1100,109 @@ export interface OutPoint { outputIndex: number; } +export interface SubscribeReceiveEventsRequest { + /** + * Filter receives by a specific address. Leave empty to get all receive + * events for all addresses. + */ + filterAddr: string; + /** + * The start time as a Unix timestamp in microseconds. If not set (default + * value 0), the daemon will start streaming events from the current time. + */ + startTimestamp: string; +} + +export interface ReceiveEvent { + /** Event creation timestamp (Unix timestamp in microseconds). */ + timestamp: string; + /** The address that received the asset. */ + address: Addr | undefined; + /** The outpoint of the transaction that was used to receive the asset. */ + outpoint: string; + /** + * The status of the event. If error below is set, then the status is the + * state that lead to the error during its execution. + */ + status: AddrEventStatus; + /** + * The height of the block the asset receive transaction was mined in. This + * is only set if the status is ADDR_EVENT_STATUS_TRANSACTION_CONFIRMED or + * later. + */ + confirmationHeight: number; + /** An optional error, indicating that executing the status above failed. */ + error: string; +} + +export interface SubscribeSendEventsRequest { + /** + * Filter send events by a specific recipient script key. Leave empty to get + * all receive events for all parcels. + */ + filterScriptKey: Uint8Array | string; +} + +export interface SendEvent { + /** Execute timestamp (Unix timestamp in microseconds). */ + timestamp: string; + /** + * The send state that was executed successfully. If error below is set, + * then the send_state is the state that lead to the error during its + * execution. + */ + sendState: string; + /** The type of the outbound send parcel. */ + parcelType: ParcelType; + /** + * The list of addresses the parcel sends to (recipient addresses only, not + * including change going back to own wallet). This is only set for parcels + * of type PARCEL_TYPE_ADDRESS. + */ + addresses: Addr[]; + /** The virtual packets that are part of the parcel. */ + virtualPackets: Uint8Array | string[]; + /** + * The passive virtual packets that are carried along with the parcel. This + * is empty if there were no other assets in the input commitment that is + * being spent with the "active" virtual packets above. + */ + passiveVirtualPackets: Uint8Array | string[]; + /** + * The Bitcoin on-chain anchor transaction that commits the sent assets + * on-chain. This is only set after the send state SEND_STATE_ANCHOR_SIGN. + */ + anchorTransaction: AnchorTransaction | undefined; + /** + * The final transfer as it will be stored in the database. This is only set + * after the send state SEND_STATE_LOG_COMMITMENT. + */ + transfer: AssetTransfer | undefined; + /** An optional error, indicating that executing the send_state failed. */ + error: string; +} + +export interface AnchorTransaction { + anchorPsbt: Uint8Array | string; + /** The index of the (added) change output or -1 if no change was left over. */ + changeOutputIndex: number; + /** + * The total number of satoshis in on-chain fees paid by the anchor + * transaction. + */ + chainFeesSats: string; + /** The fee rate in sat/kWU that was targeted by the anchor transaction. */ + targetFeeRateSatKw: number; + /** + * The list of UTXO lock leases that were acquired for the inputs in the funded + * PSBT packet from lnd. Only inputs added to the PSBT by this RPC are locked, + * inputs that were already present in the PSBT are not locked. + */ + lndLockedUtxos: OutPoint[]; + /** The final, signed anchor transaction that was broadcast to the network. */ + finalTx: Uint8Array | string; +} + export interface TaprootAssets { /** * tapcli: `assets list` @@ -983,29 +1325,20 @@ export interface TaprootAssets { burnAsset( request?: DeepPartial ): Promise; + /** + * tapcli: `assets listburns` + * ListBurns lists the asset burns that this wallet has performed. These assets + * are not recoverable in any way. Filters may be applied to return more + * specific results. + */ + listBurns( + request?: DeepPartial + ): Promise; /** * tapcli: `getinfo` * GetInfo returns the information for the node. */ getInfo(request?: DeepPartial): Promise; - /** - * SubscribeSendAssetEventNtfns registers a subscription to the event - * notification stream which relates to the asset sending process. - */ - subscribeSendAssetEventNtfns( - request?: DeepPartial, - onMessage?: (msg: SendAssetEvent) => void, - onError?: (err: Error) => void - ): void; - /** - * SubscribeReceiveAssetEventNtfns registers a subscription to the event - * notification stream which relates to the asset receive process. - */ - subscribeReceiveAssetEventNtfns( - request?: DeepPartial, - onMessage?: (msg: ReceiveAssetEvent) => void, - onError?: (err: Error) => void - ): void; /** * tapcli: `assets meta` * FetchAssetMeta allows a caller to fetch the reveal meta data for an asset @@ -1014,6 +1347,26 @@ export interface TaprootAssets { fetchAssetMeta( request?: DeepPartial ): Promise; + /** + * tapcli: `events receive` + * SubscribeReceiveEvents allows a caller to subscribe to receive events for + * incoming asset transfers. + */ + subscribeReceiveEvents( + request?: DeepPartial, + onMessage?: (msg: ReceiveEvent) => void, + onError?: (err: Error) => void + ): void; + /** + * tapcli: `events send` + * SubscribeSendEvents allows a caller to subscribe to send events for outgoing + * asset transfers. + */ + subscribeSendEvents( + request?: DeepPartial, + onMessage?: (msg: SendEvent) => void, + onError?: (err: Error) => void + ): void; } type Builtin = diff --git a/lib/types/proto/tapd/universerpc/universe.ts b/lib/types/proto/tapd/universerpc/universe.ts index c490eed..c6f7d36 100644 --- a/lib/types/proto/tapd/universerpc/universe.ts +++ b/lib/types/proto/tapd/universerpc/universe.ts @@ -47,6 +47,23 @@ export enum AssetTypeFilter { UNRECOGNIZED = 'UNRECOGNIZED' } +export interface MultiverseRootRequest { + /** The proof type to calculate the multiverse root for. */ + proofType: ProofType; + /** + * An optional list of universe IDs to include in the multiverse root. If + * none are specified, then all known universes of the given proof type are + * included. NOTE: The proof type within the IDs must either be unspecified + * or match the proof type above. + */ + specificIds: ID[]; +} + +export interface MultiverseRootResponse { + /** The root of the multiverse tree. */ + multiverseRoot: MerkleSumNode | undefined; +} + export interface AssetRootRequest { /** * If true, then the response will include the amounts for each asset ID @@ -199,7 +216,7 @@ export interface UniverseKey { } export interface AssetProofResponse { - /** The request original request for the issuance proof. */ + /** The original request for the issuance proof. */ req: UniverseKey | undefined; /** The Universe root that includes this asset leaf. */ universeRoot: UniverseRoot | undefined; @@ -229,6 +246,18 @@ export interface AssetProof { assetLeaf: AssetLeaf | undefined; } +export interface PushProofRequest { + /** The ID of the asset to push the proof for. */ + key: UniverseKey | undefined; + /** The universe server to push the proof to. */ + server: UniverseFederationServer | undefined; +} + +export interface PushProofResponse { + /** The ID of the asset a push was requested for. */ + key: UniverseKey | undefined; +} + export interface InfoRequest {} export interface InfoResponse { @@ -439,6 +468,15 @@ export interface QueryFederationSyncConfigResponse { } export interface Universe { + /** + * tapcli: `universe multiverse` + * MultiverseRoot returns the root of the multiverse tree. This is useful to + * determine the equality of two multiverse trees, since the root can directly + * be compared to another multiverse root to find out if a sync is required. + */ + multiverseRoot( + request?: DeepPartial + ): Promise; /** * tapcli: `universe roots` * AssetRoots queries for the known Universe roots associated with each known @@ -502,6 +540,15 @@ export interface Universe { * updated asset_id/group_key. */ insertProof(request?: DeepPartial): Promise; + /** + * tapcli: `universe proofs push` + * PushProof attempts to query the local universe for a proof specified by a + * UniverseKey. If found, a connection is made to a remote Universe server to + * attempt to upload the asset leaf. + */ + pushProof( + request?: DeepPartial + ): Promise; /** * tapcli: `universe info` * Info returns a set of information about the current state of the Universe. diff --git a/lib/types/proto/tapdevrpc.ts b/lib/types/proto/tapdevrpc.ts new file mode 100644 index 0000000..f864320 --- /dev/null +++ b/lib/types/proto/tapdevrpc.ts @@ -0,0 +1 @@ +export * from './tapd/tapdevrpc/tapdev'; diff --git a/package.json b/package.json index 0aa01d2..efd842e 100644 --- a/package.json +++ b/package.json @@ -5,12 +5,12 @@ "main": "./dist/index.js", "types": "./dist/index.d.ts", "config": { - "lnd_release_tag": "v0.18.2-beta", + "lnd_release_tag": "v0.18.4-beta.rc2", "loop_release_tag": "v0.28.5-beta", "pool_release_tag": "v0.6.5-beta", "faraday_release_tag": "v0.2.13-alpha", - "tapd_release_tag": "v0-3-3-lnd-18", - "lit_release_tag": "v0.13.2-alpha", + "tapd_release_tag": "v0.5.0-rc2", + "lit_release_tag": "v0.14.0-alpha.rc2", "protoc_version": "21.9" }, "scripts": { diff --git a/protos/lit/v0.13.2-alpha/firewall.proto b/protos/lit/v0.14.0-alpha.rc2/firewall.proto similarity index 100% rename from protos/lit/v0.13.2-alpha/firewall.proto rename to protos/lit/v0.14.0-alpha.rc2/firewall.proto diff --git a/protos/lit/v0.13.2-alpha/lit-autopilot.proto b/protos/lit/v0.14.0-alpha.rc2/lit-autopilot.proto similarity index 100% rename from protos/lit/v0.13.2-alpha/lit-autopilot.proto rename to protos/lit/v0.14.0-alpha.rc2/lit-autopilot.proto diff --git a/protos/lit/v0.13.2-alpha/lit-sessions.proto b/protos/lit/v0.14.0-alpha.rc2/lit-sessions.proto similarity index 100% rename from protos/lit/v0.13.2-alpha/lit-sessions.proto rename to protos/lit/v0.14.0-alpha.rc2/lit-sessions.proto diff --git a/protos/lit/v0.13.2-alpha/lit-status.proto b/protos/lit/v0.14.0-alpha.rc2/lit-status.proto similarity index 100% rename from protos/lit/v0.13.2-alpha/lit-status.proto rename to protos/lit/v0.14.0-alpha.rc2/lit-status.proto diff --git a/protos/lnd/v0.18.2-beta/autopilotrpc/autopilot.proto b/protos/lnd/v0.18.4-beta.rc2/autopilotrpc/autopilot.proto similarity index 100% rename from protos/lnd/v0.18.2-beta/autopilotrpc/autopilot.proto rename to protos/lnd/v0.18.4-beta.rc2/autopilotrpc/autopilot.proto diff --git a/protos/lnd/v0.18.2-beta/chainrpc/chainnotifier.proto b/protos/lnd/v0.18.4-beta.rc2/chainrpc/chainnotifier.proto similarity index 100% rename from protos/lnd/v0.18.2-beta/chainrpc/chainnotifier.proto rename to protos/lnd/v0.18.4-beta.rc2/chainrpc/chainnotifier.proto diff --git a/protos/lnd/v0.18.2-beta/invoicesrpc/invoices.proto b/protos/lnd/v0.18.4-beta.rc2/invoicesrpc/invoices.proto similarity index 73% rename from protos/lnd/v0.18.2-beta/invoicesrpc/invoices.proto rename to protos/lnd/v0.18.4-beta.rc2/invoicesrpc/invoices.proto index 7afffba..d9d3bc1 100644 --- a/protos/lnd/v0.18.2-beta/invoicesrpc/invoices.proto +++ b/protos/lnd/v0.18.4-beta.rc2/invoicesrpc/invoices.proto @@ -55,10 +55,19 @@ service Invoices { rpc SettleInvoice (SettleInvoiceMsg) returns (SettleInvoiceResp); /* - LookupInvoiceV2 attempts to look up at invoice. An invoice can be refrenced + LookupInvoiceV2 attempts to look up at invoice. An invoice can be referenced using either its payment hash, payment address, or set ID. */ rpc LookupInvoiceV2 (LookupInvoiceMsg) returns (lnrpc.Invoice); + + /* + HtlcModifier is a bidirectional streaming RPC that allows a client to + intercept and modify the HTLCs that attempt to settle the given invoice. The + server will send HTLCs of invoices to the client and the client can modify + some aspects of the HTLC in order to pass the invoice acceptance tests. + */ + rpc HtlcModifier (stream HtlcModifyResponse) + returns (stream HtlcModifyRequest); } message CancelInvoiceMsg { @@ -192,3 +201,51 @@ message LookupInvoiceMsg { LookupModifier lookup_modifier = 4; } + +// CircuitKey is a unique identifier for an HTLC. +message CircuitKey { + // The id of the channel that the is part of this circuit. + uint64 chan_id = 1; + + // The index of the incoming htlc in the incoming channel. + uint64 htlc_id = 2; +} + +message HtlcModifyRequest { + // The invoice the intercepted HTLC is attempting to settle. The HTLCs in + // the invoice are only HTLCs that have already been accepted or settled, + // not including the current intercepted HTLC. + lnrpc.Invoice invoice = 1; + + // The unique identifier of the HTLC of this intercepted HTLC. + CircuitKey exit_htlc_circuit_key = 2; + + // The amount in milli-satoshi that the exit HTLC is attempting to pay. + uint64 exit_htlc_amt = 3; + + // The absolute expiry height of the exit HTLC. + uint32 exit_htlc_expiry = 4; + + // The current block height. + uint32 current_height = 5; + + // The wire message custom records of the exit HTLC. + map exit_htlc_wire_custom_records = 6; +} + +message HtlcModifyResponse { + // The circuit key of the HTLC that the client wants to modify. + CircuitKey circuit_key = 1; + + // The modified amount in milli-satoshi that the exit HTLC is paying. This + // value can be different from the actual on-chain HTLC amount, in case the + // HTLC carries other valuable items, as can be the case with custom channel + // types. + optional uint64 amt_paid = 2; + + // This flag indicates whether the HTLCs associated with the invoices should + // be cancelled. The interceptor client may set this field if some + // unexpected behavior is encountered. Setting this will ignore the amt_paid + // field. + bool cancel_set = 3; +} diff --git a/protos/lnd/v0.18.2-beta/lightning.proto b/protos/lnd/v0.18.4-beta.rc2/lightning.proto similarity index 97% rename from protos/lnd/v0.18.2-beta/lightning.proto rename to protos/lnd/v0.18.4-beta.rc2/lightning.proto index 6356a6b..6449305 100644 --- a/protos/lnd/v0.18.2-beta/lightning.proto +++ b/protos/lnd/v0.18.4-beta.rc2/lightning.proto @@ -1190,9 +1190,8 @@ message SendCoinsRequest { int64 sat_per_byte = 5 [deprecated = true]; /* - If set, then the amount field will be ignored, and lnd will attempt to - send all the coins under control of the internal wallet to the specified - address. + If set, the amount field should be unset. It indicates lnd will send all + wallet coins or all selected coins to the specified address. */ bool send_all = 6; @@ -1208,6 +1207,9 @@ message SendCoinsRequest { // The strategy to use for selecting coins. CoinSelectionStrategy coin_selection_strategy = 10; + + // A list of selected outpoints as inputs for the transaction. + repeated OutPoint outpoints = 11; } message SendCoinsResponse { // The transaction ID of the transaction @@ -1386,8 +1388,14 @@ enum CommitmentType { A channel that uses musig2 for the funding output, and the new tapscript features where relevant. */ - // TODO(roasbeef): need script enforce mirror type for the above as well? SIMPLE_TAPROOT = 5; + + /* + Identical to the SIMPLE_TAPROOT channel type, but with extra functionality. + This channel type also commits to additional meta data in the tapscript + leaves for the scripts in a channel. + */ + SIMPLE_TAPROOT_OVERLAY = 6; } message ChannelConstraints { @@ -1590,6 +1598,11 @@ message Channel { the channel's operation. */ string memo = 36; + + /* + Custom channel data that might be populated in custom channels. + */ + bytes custom_channel_data = 37; } message ListChannelsRequest { @@ -2026,10 +2039,38 @@ message ChannelOpenUpdate { ChannelPoint channel_point = 1; } +message CloseOutput { + // The amount in satoshi of this close output. This amount is the final + // commitment balance of the channel and the actual amount paid out on chain + // might be smaller due to subtracted fees. + int64 amount_sat = 1; + + // The pkScript of the close output. + bytes pk_script = 2; + + // Whether this output is for the local or remote node. + bool is_local = 3; + + // The TLV encoded custom channel data records for this output, which might + // be set for custom channels. + bytes custom_channel_data = 4; +} + message ChannelCloseUpdate { bytes closing_txid = 1; bool success = 2; + + // The local channel close output. If the local channel balance was dust to + // begin with, this output will not be set. + CloseOutput local_close_output = 3; + + // The remote channel close output. If the remote channel balance was dust + // to begin with, this output will not be set. + CloseOutput remote_close_output = 4; + + // Any additional outputs that might be added for custom channel types. + repeated CloseOutput additional_outputs = 5; } message CloseChannelRequest { @@ -2707,6 +2748,11 @@ message PendingChannelsResponse { impacts the channel's operation. */ string memo = 13; + + /* + Custom channel data that might be populated in custom channels. + */ + bytes custom_channel_data = 34; } message PendingOpenChannel { @@ -2966,6 +3012,12 @@ message ChannelBalanceResponse { // Sum of channels pending remote balances. Amount pending_open_remote_balance = 8; + + /* + Custom channel data that might be populated if there are custom channels + present. + */ + bytes custom_channel_data = 9; } message QueryRoutesRequest { @@ -3291,6 +3343,20 @@ message Route { The total amount in millisatoshis. */ int64 total_amt_msat = 6; + + /* + The actual on-chain amount that was sent out to the first hop. This value is + only different from the total_amt_msat field if this is a custom channel + payment and the value transported in the HTLC is different from the BTC + amount in the HTLC. If this value is zero, then this is an old payment that + didn't have this value yet and can be ignored. + */ + int64 first_hop_amount_msat = 7; + + /* + Custom channel data that might be populated in custom channels. + */ + bytes custom_channel_data = 8; } message NodeInfoRequest { @@ -3443,6 +3509,10 @@ message ChanInfoRequest { output index for the channel. */ uint64 chan_id = 1 [jstype = JS_STRING]; + + // The channel point of the channel in format funding_txid:output_index. If + // chan_id is specified, this field is ignored. + string chan_point = 2; } message NetworkInfoRequest { @@ -3832,6 +3902,48 @@ message Invoice { Note: Output only, don't specify for creating an invoice. */ map amp_invoice_state = 28; + + /* + Signals that the invoice should include blinded paths to hide the true + identity of the recipient. + */ + bool is_blinded = 29; + + /* + Config values to use when creating blinded paths for this invoice. These + can be used to override the defaults config values provided in by the + global config. This field is only used if is_blinded is true. + */ + BlindedPathConfig blinded_path_config = 30; +} + +message BlindedPathConfig { + /* + The minimum number of real hops to include in a blinded path. This doesn't + include our node, so if the minimum is 1, then the path will contain at + minimum our node along with an introduction node hop. If it is zero then + the shortest path will use our node as an introduction node. + */ + optional uint32 min_num_real_hops = 1; + + /* + The number of hops to include in a blinded path. This doesn't include our + node, so if it is 1, then the path will contain our node along with an + introduction node or dummy node hop. If paths shorter than NumHops is + found, then they will be padded using dummy hops. + */ + optional uint32 num_hops = 2; + + /* + The maximum number of blinded paths to select and add to an invoice. + */ + optional uint32 max_num_paths = 3; + + /* + A list of node IDs of nodes that should not be used in any of our generated + blinded paths. + */ + repeated bytes node_omission_list = 4; } enum InvoiceHTLCState { @@ -3874,6 +3986,11 @@ message InvoiceHTLC { // Details relevant to AMP HTLCs, only populated if this is an AMP HTLC. AMP amp = 11; + + /* + Custom channel data that might be populated in custom channels. + */ + bytes custom_channel_data = 12; } // Details specific to AMP HTLCs. @@ -4040,6 +4157,11 @@ enum PaymentFailureReason { Insufficient local balance. */ FAILURE_REASON_INSUFFICIENT_BALANCE = 5; + + /* + The payment was canceled. + */ + FAILURE_REASON_CANCELED = 6; } message Payment { @@ -4109,6 +4231,12 @@ message Payment { uint64 payment_index = 15; PaymentFailureReason failure_reason = 16; + + /* + The custom TLV records that were sent to the first hop as part of the HTLC + wire message for this payment. + */ + map first_hop_custom_records = 17; } message HTLCAttempt { @@ -4285,6 +4413,7 @@ message PayReq { bytes payment_addr = 11; int64 num_msat = 12; map features = 13; + repeated BlindedPaymentPath blinded_paths = 14; } enum FeatureBit { diff --git a/protos/lnd/v0.18.2-beta/routerrpc/router.proto b/protos/lnd/v0.18.4-beta.rc2/routerrpc/router.proto similarity index 88% rename from protos/lnd/v0.18.2-beta/routerrpc/router.proto rename to protos/lnd/v0.18.4-beta.rc2/routerrpc/router.proto index a909828..92da751 100644 --- a/protos/lnd/v0.18.2-beta/routerrpc/router.proto +++ b/protos/lnd/v0.18.4-beta.rc2/routerrpc/router.proto @@ -176,6 +176,25 @@ service Router { */ rpc UpdateChanStatus (UpdateChanStatusRequest) returns (UpdateChanStatusResponse); + + /* + XAddLocalChanAliases is an experimental API that creates a set of new + channel SCID alias mappings. The final total set of aliases in the manager + after the add operation is returned. This is only a locally stored alias, + and will not be communicated to the channel peer via any message. Therefore, + routing over such an alias will only work if the peer also calls this same + RPC on their end. If an alias already exists, an error is returned + */ + rpc XAddLocalChanAliases (AddAliasesRequest) returns (AddAliasesResponse); + + /* + XDeleteLocalChanAliases is an experimental API that deletes a set of alias + mappings. The final total set of aliases in the manager after the delete + operation is returned. The deletion will not be communicated to the channel + peer via any message. + */ + rpc XDeleteLocalChanAliases (DeleteAliasesRequest) + returns (DeleteAliasesResponse); } message SendPaymentRequest { @@ -330,6 +349,24 @@ message SendPaymentRequest { only, to 1 to optimize for reliability only or a value inbetween for a mix. */ double time_pref = 23; + + /* + If set, the payment loop can be interrupted by manually canceling the + payment context, even before the payment timeout is reached. Note that the + payment may still succeed after cancellation, as in-flight attempts can + still settle afterwards. Canceling will only prevent further attempts from + being sent. + */ + bool cancelable = 24; + + /* + An optional field that can be used to pass an arbitrary set of TLV records + to the first hop peer of this payment. This can be used to pass application + specific data during the payment attempt. Record types are required to be in + the custom range >= 65536. When using REST, the values must be encoded as + base64. + */ + map first_hop_custom_records = 25; } message TrackPaymentRequest { @@ -423,6 +460,15 @@ message SendToRouteRequest { routes, incorrect payment details, or insufficient funds. */ bool skip_temp_err = 3; + + /* + An optional field that can be used to pass an arbitrary set of TLV records + to the first hop peer of this payment. This can be used to pass application + specific data during the payment attempt. Record types are required to be in + the custom range >= 65536. When using REST, the values must be encoded as + base64. + */ + map first_hop_custom_records = 4; } message SendToRouteResponse { @@ -698,6 +744,15 @@ message BuildRouteRequest { This is also called payment secret in specifications (e.g. BOLT 11). */ bytes payment_addr = 5; + + /* + An optional field that can be used to pass an arbitrary set of TLV records + to the first hop peer of this payment. This can be used to pass application + specific data during the payment attempt. Record types are required to be in + the custom range >= 65536. When using REST, the values must be encoded as + base64. + */ + map first_hop_custom_records = 6; } message BuildRouteResponse { @@ -954,12 +1009,17 @@ message ForwardHtlcInterceptRequest { // The block height at which this htlc will be auto-failed to prevent the // channel from force-closing. int32 auto_fail_height = 10; + + // The custom records of the peer's incoming p2p wire message. + map in_wire_custom_records = 11; } /** ForwardHtlcInterceptResponse enables the caller to resolve a previously hold forward. The caller can choose either to: - `Resume`: Execute the default behavior (usually forward). +- `ResumeModified`: Execute the default behavior (usually forward) with HTLC + field modifications. - `Reject`: Fail the htlc backwards. - `Settle`: Settle this htlc with a given preimage. */ @@ -990,12 +1050,36 @@ message ForwardHtlcInterceptResponse { // For backwards-compatibility reasons, TEMPORARY_CHANNEL_FAILURE is the // default value for this field. lnrpc.Failure.FailureCode failure_code = 5; + + // The amount that was set on the p2p wire message of the incoming HTLC. + // This field is ignored if the action is not RESUME_MODIFIED or the amount + // is zero. + uint64 in_amount_msat = 6; + + // The amount to set on the p2p wire message of the resumed HTLC. This field + // is ignored if the action is not RESUME_MODIFIED or the amount is zero. + uint64 out_amount_msat = 7; + + // Any custom records that should be set on the p2p wire message message of + // the resumed HTLC. This field is ignored if the action is not + // RESUME_MODIFIED. + map out_wire_custom_records = 8; } enum ResolveHoldForwardAction { + // SETTLE is an action that is used to settle an HTLC instead of forwarding + // it. SETTLE = 0; + + // FAIL is an action that is used to fail an HTLC backwards. FAIL = 1; + + // RESUME is an action that is used to resume a forward HTLC. RESUME = 2; + + // RESUME_MODIFIED is an action that is used to resume a hold forward HTLC + // with modifications specified during interception. + RESUME_MODIFIED = 3; } message UpdateChanStatusRequest { @@ -1012,3 +1096,19 @@ enum ChanStatusAction { message UpdateChanStatusResponse { } + +message AddAliasesRequest { + repeated lnrpc.AliasMap alias_maps = 1; +} + +message AddAliasesResponse { + repeated lnrpc.AliasMap alias_maps = 1; +} + +message DeleteAliasesRequest { + repeated lnrpc.AliasMap alias_maps = 1; +} + +message DeleteAliasesResponse { + repeated lnrpc.AliasMap alias_maps = 1; +} \ No newline at end of file diff --git a/protos/lnd/v0.18.2-beta/signrpc/signer.proto b/protos/lnd/v0.18.4-beta.rc2/signrpc/signer.proto similarity index 100% rename from protos/lnd/v0.18.2-beta/signrpc/signer.proto rename to protos/lnd/v0.18.4-beta.rc2/signrpc/signer.proto diff --git a/protos/lnd/v0.18.2-beta/walletrpc/walletkit.proto b/protos/lnd/v0.18.4-beta.rc2/walletrpc/walletkit.proto similarity index 99% rename from protos/lnd/v0.18.2-beta/walletrpc/walletkit.proto rename to protos/lnd/v0.18.4-beta.rc2/walletrpc/walletkit.proto index b861803..ec33024 100644 --- a/protos/lnd/v0.18.2-beta/walletrpc/walletkit.proto +++ b/protos/lnd/v0.18.4-beta.rc2/walletrpc/walletkit.proto @@ -839,6 +839,9 @@ message EstimateFeeResponse { confirmation target in the request. */ int64 sat_per_kw = 1; + + // The current minimum relay fee based on our chain backend in sat/kw. + int64 min_relay_fee_sat_per_kw = 2; } enum WitnessType { diff --git a/protos/lnd/v0.18.2-beta/walletunlocker.proto b/protos/lnd/v0.18.4-beta.rc2/walletunlocker.proto similarity index 100% rename from protos/lnd/v0.18.2-beta/walletunlocker.proto rename to protos/lnd/v0.18.4-beta.rc2/walletunlocker.proto diff --git a/protos/lnd/v0.18.2-beta/watchtowerrpc/watchtower.proto b/protos/lnd/v0.18.4-beta.rc2/watchtowerrpc/watchtower.proto similarity index 100% rename from protos/lnd/v0.18.2-beta/watchtowerrpc/watchtower.proto rename to protos/lnd/v0.18.4-beta.rc2/watchtowerrpc/watchtower.proto diff --git a/protos/lnd/v0.18.2-beta/wtclientrpc/wtclient.proto b/protos/lnd/v0.18.4-beta.rc2/wtclientrpc/wtclient.proto similarity index 100% rename from protos/lnd/v0.18.2-beta/wtclientrpc/wtclient.proto rename to protos/lnd/v0.18.4-beta.rc2/wtclientrpc/wtclient.proto diff --git a/protos/tapd/v0-3-3-lnd-18/assetwalletrpc/assetwallet.proto b/protos/tapd/v0-3-3-lnd-18/assetwalletrpc/assetwallet.proto deleted file mode 100644 index c73240d..0000000 --- a/protos/tapd/v0-3-3-lnd-18/assetwalletrpc/assetwallet.proto +++ /dev/null @@ -1,213 +0,0 @@ -syntax = "proto3"; - -import "taprootassets.proto"; - -package assetwalletrpc; - -option go_package = "github.com/lightninglabs/taproot-assets/taprpc/assetwalletrpc"; - -service AssetWallet { - /* - FundVirtualPsbt selects inputs from the available asset commitments to fund - a virtual transaction matching the template. - */ - rpc FundVirtualPsbt (FundVirtualPsbtRequest) - returns (FundVirtualPsbtResponse); - - /* - SignVirtualPsbt signs the inputs of a virtual transaction and prepares the - commitments of the inputs and outputs. - */ - rpc SignVirtualPsbt (SignVirtualPsbtRequest) - returns (SignVirtualPsbtResponse); - - /* - AnchorVirtualPsbts merges and then commits multiple virtual transactions in - a single BTC level anchor transaction. - - TODO(guggero): Actually implement accepting and merging multiple - transactions. - */ - rpc AnchorVirtualPsbts (AnchorVirtualPsbtsRequest) - returns (taprpc.SendAssetResponse); - - /* - NextInternalKey derives the next internal key for the given key family and - stores it as an internal key in the database to make sure it is identified - as a local key later on when importing proofs. While an internal key can - also be used as the internal key of a script key, it is recommended to use - the NextScriptKey RPC instead, to make sure the tweaked Taproot output key - is also recognized as a local key. - */ - rpc NextInternalKey (NextInternalKeyRequest) - returns (NextInternalKeyResponse); - - /* - NextScriptKey derives the next script key (and its corresponding internal - key) and stores them both in the database to make sure they are identified - as local keys later on when importing proofs. - */ - rpc NextScriptKey (NextScriptKeyRequest) returns (NextScriptKeyResponse); - - /* tapcli: `proofs proveownership` - ProveAssetOwnership creates an ownership proof embedded in an asset - transition proof. That ownership proof is a signed virtual transaction - spending the asset with a valid witness to prove the prover owns the keys - that can spend the asset. - */ - rpc ProveAssetOwnership (ProveAssetOwnershipRequest) - returns (ProveAssetOwnershipResponse); - - /* tapcli: `proofs verifyownership` - VerifyAssetOwnership verifies the asset ownership proof embedded in the - given transition proof of an asset and returns true if the proof is valid. - */ - rpc VerifyAssetOwnership (VerifyAssetOwnershipRequest) - returns (VerifyAssetOwnershipResponse); - - /* - RemoveUTXOLease removes the lease/lock/reservation of the given managed - UTXO. - */ - rpc RemoveUTXOLease (RemoveUTXOLeaseRequest) - returns (RemoveUTXOLeaseResponse); -} - -message FundVirtualPsbtRequest { - oneof template { - /* - Use an existing PSBT packet as the template for the funded PSBT. - - TODO(guggero): Actually implement this. We can't use the "reserved" - keyword here because we're in a oneof, so we add the field but implement - it later. - */ - bytes psbt = 1; - - /* - Use the asset outputs and optional asset inputs from this raw template. - */ - TxTemplate raw = 2; - } -} - -message FundVirtualPsbtResponse { - /* - The funded but not yet signed PSBT packet. - */ - bytes funded_psbt = 1; - - /* - The index of the added change output or -1 if no change was left over. - */ - int32 change_output_index = 2; -} - -message TxTemplate { - /* - An optional list of inputs to use. Every input must be an asset UTXO known - to the wallet. The sum of all inputs must be greater than or equal to the - sum of all outputs. - - If no inputs are specified, asset coin selection will be performed instead - and inputs of sufficient value will be added to the resulting PSBT. - */ - repeated PrevId inputs = 1; - - /* - A map of all Taproot Asset addresses mapped to the anchor transaction's - output index that should be sent to. - */ - map recipients = 2; -} - -message PrevId { - /* - The bitcoin anchor output on chain that contains the input asset. - */ - taprpc.OutPoint outpoint = 1; - - /* - The asset ID of the previous asset tree. - */ - bytes id = 2; - - /* - The tweaked Taproot output key committing to the possible spending - conditions of the asset. - */ - bytes script_key = 3; -} - -message SignVirtualPsbtRequest { - /* - The PSBT of the virtual transaction that should be signed. The PSBT must - contain all required inputs, outputs, UTXO data and custom fields required - to identify the signing key. - */ - bytes funded_psbt = 1; -} - -message SignVirtualPsbtResponse { - /* - The signed virtual transaction in PSBT format. - */ - bytes signed_psbt = 1; - - /* - The indices of signed inputs. - */ - repeated uint32 signed_inputs = 2; -} - -message AnchorVirtualPsbtsRequest { - /* - The list of virtual transactions that should be merged and committed to in - the BTC level anchor transaction. - */ - repeated bytes virtual_psbts = 1; -} - -message NextInternalKeyRequest { - uint32 key_family = 1; -} - -message NextInternalKeyResponse { - taprpc.KeyDescriptor internal_key = 1; -} - -message NextScriptKeyRequest { - uint32 key_family = 1; -} - -message NextScriptKeyResponse { - taprpc.ScriptKey script_key = 1; -} - -message ProveAssetOwnershipRequest { - bytes asset_id = 1; - - bytes script_key = 2; - - taprpc.OutPoint outpoint = 3; -} - -message ProveAssetOwnershipResponse { - bytes proof_with_witness = 1; -} - -message VerifyAssetOwnershipRequest { - bytes proof_with_witness = 1; -} - -message VerifyAssetOwnershipResponse { - bool valid_proof = 1; -} - -message RemoveUTXOLeaseRequest { - // The outpoint of the UTXO to remove the lease for. - taprpc.OutPoint outpoint = 1; -} - -message RemoveUTXOLeaseResponse { -} diff --git a/protos/tapd/v0-3-3-lnd-18/mintrpc/mint.proto b/protos/tapd/v0-3-3-lnd-18/mintrpc/mint.proto deleted file mode 100644 index d632e02..0000000 --- a/protos/tapd/v0-3-3-lnd-18/mintrpc/mint.proto +++ /dev/null @@ -1,210 +0,0 @@ -syntax = "proto3"; - -import "taprootassets.proto"; - -package mintrpc; - -option go_package = "github.com/lightninglabs/taproot-assets/taprpc/mintrpc"; - -service Mint { - /* tapcli: `assets mint` - MintAsset will attempt to mint the set of assets (async by default to - ensure proper batching) specified in the request. The pending batch is - returned that shows the other pending assets that are part of the next - batch. This call will block until the operation succeeds (asset is staged - in the batch) or fails. - */ - rpc MintAsset (MintAssetRequest) returns (MintAssetResponse); - - /* tapcli: `assets mint finalize` - FinalizeBatch will attempt to finalize the current pending batch. - */ - rpc FinalizeBatch (FinalizeBatchRequest) returns (FinalizeBatchResponse); - - /* tapcli: `assets mint cancel` - CancelBatch will attempt to cancel the current pending batch. - */ - rpc CancelBatch (CancelBatchRequest) returns (CancelBatchResponse); - - /* tapcli: `assets mint batches` - ListBatches lists the set of batches submitted to the daemon, including - pending and cancelled batches. - */ - rpc ListBatches (ListBatchRequest) returns (ListBatchResponse); -} - -message PendingAsset { - // The version of asset to mint. - taprpc.AssetVersion asset_version = 1; - - // The type of the asset to be created. - taprpc.AssetType asset_type = 2; - - // The name, or "tag" of the asset. This will affect the final asset ID. - string name = 3; - - /* - A blob that resents metadata related to the asset. This will affect the - final asset ID. - */ - taprpc.AssetMeta asset_meta = 4; - - /* - The total amount of units of the new asset that should be created. If the - AssetType is Collectible, then this field cannot be set. - */ - uint64 amount = 5; - - /* - If true, then the asset will be created with a new group key, which allows - for future asset issuance. - */ - bool new_grouped_asset = 6; - - // The specific group key this asset should be minted with. - bytes group_key = 7; - - /* - The name of the asset in the batch that will anchor a new asset group. - This asset will be minted with the same group key as the anchor asset. - */ - string group_anchor = 8; -} - -message MintAsset { - // The version of asset to mint. - taprpc.AssetVersion asset_version = 1; - - // The type of the asset to be created. - taprpc.AssetType asset_type = 2; - - // The name, or "tag" of the asset. This will affect the final asset ID. - string name = 3; - - /* - A blob that resents metadata related to the asset. This will affect the - final asset ID. - */ - taprpc.AssetMeta asset_meta = 4; - - /* - The total amount of units of the new asset that should be created. If the - AssetType is Collectible, then this field cannot be set. - */ - uint64 amount = 5; - - /* - If true, then the asset will be created with a group key, which allows for - future asset issuance. - */ - bool new_grouped_asset = 6; - - /* - If true, then a group key or group anchor can be set to mint this asset into - an existing asset group. - */ - bool grouped_asset = 7; - - // The specific group key this asset should be minted with. - bytes group_key = 8; - - /* - The name of the asset in the batch that will anchor a new asset group. - This asset will be minted with the same group key as the anchor asset. - */ - string group_anchor = 9; -} - -message MintAssetRequest { - /* - The asset to be minted. - */ - MintAsset asset = 1; - - /* - If true, then the assets currently in the batch won't be returned in the - response. This is mainly to avoid a lot of data being transmitted and - possibly printed on the command line in the case of a very large batch. - */ - bool short_response = 2; -} - -message MintAssetResponse { - // The pending batch the asset was added to. - MintingBatch pending_batch = 1; -} - -message MintingBatch { - /* - A public key serialized in compressed format that can be used to uniquely - identify a pending minting batch. Responses that share the same key will be - batched into the same minting transaction. - */ - bytes batch_key = 1; - - /* - The transaction ID of the batch. Only populated if the batch has been - committed. - */ - string batch_txid = 2; - - // The state of the batch. - BatchState state = 3; - - // The assets that are part of the batch. - repeated PendingAsset assets = 4; -} - -enum BatchState { - BATCH_STATE_UNKNOWN = 0; - BATCH_STATE_PENDING = 1; - BATCH_STATE_FROZEN = 2; - BATCH_STATE_COMMITTED = 3; - BATCH_STATE_BROADCAST = 4; - BATCH_STATE_CONFIRMED = 5; - BATCH_STATE_FINALIZED = 6; - BATCH_STATE_SEEDLING_CANCELLED = 7; - BATCH_STATE_SPROUT_CANCELLED = 8; -} - -message FinalizeBatchRequest { - /* - If true, then the assets currently in the batch won't be returned in the - response. This is mainly to avoid a lot of data being transmitted and - possibly printed on the command line in the case of a very large batch. - */ - bool short_response = 1; - - // The optional fee rate to use for the minting transaction, in sat/kw. - uint32 fee_rate = 2; -} - -message FinalizeBatchResponse { - // The finalized batch. - MintingBatch batch = 1; -} - -message CancelBatchRequest { -} - -message CancelBatchResponse { - // The internal public key of the batch. - bytes batch_key = 1; -} - -message ListBatchRequest { - // The optional batch key of the batch to list. - oneof filter { - // The optional batch key of the batch to list, specified as raw bytes - // (gRPC only). - bytes batch_key = 1; - - // The optional batch key of the batch to list, specified as a hex - // encoded string (use this for REST). - string batch_key_str = 2; - } -} - -message ListBatchResponse { - repeated MintingBatch batches = 1; -} diff --git a/protos/tapd/v0.5.0-rc2/assetwalletrpc/assetwallet.proto b/protos/tapd/v0.5.0-rc2/assetwalletrpc/assetwallet.proto new file mode 100644 index 0000000..1fac8a5 --- /dev/null +++ b/protos/tapd/v0.5.0-rc2/assetwalletrpc/assetwallet.proto @@ -0,0 +1,480 @@ +syntax = "proto3"; + +import "taprootassets.proto"; + +package assetwalletrpc; + +option go_package = "github.com/lightninglabs/taproot-assets/taprpc/assetwalletrpc"; + +service AssetWallet { + /* + FundVirtualPsbt selects inputs from the available asset commitments to fund + a virtual transaction matching the template. + */ + rpc FundVirtualPsbt (FundVirtualPsbtRequest) + returns (FundVirtualPsbtResponse); + + /* + SignVirtualPsbt signs the inputs of a virtual transaction and prepares the + commitments of the inputs and outputs. + */ + rpc SignVirtualPsbt (SignVirtualPsbtRequest) + returns (SignVirtualPsbtResponse); + + /* + AnchorVirtualPsbts merges and then commits multiple virtual transactions in + a single BTC level anchor transaction. This RPC should be used if the BTC + level anchor transaction of the assets to be spent are encumbered by a + normal key and don't require any special spending conditions. For any custom + spending conditions on the BTC level, the two RPCs CommitVirtualPsbts and + PublishAndLogTransfer should be used instead (which in combination do the + same as this RPC but allow for more flexibility). + */ + rpc AnchorVirtualPsbts (AnchorVirtualPsbtsRequest) + returns (taprpc.SendAssetResponse); + + /* + CommitVirtualPsbts creates the output commitments and proofs for the given + virtual transactions by committing them to the BTC level anchor transaction. + In addition, the BTC level anchor transaction is funded and prepared up to + the point where it is ready to be signed. + */ + rpc CommitVirtualPsbts (CommitVirtualPsbtsRequest) + returns (CommitVirtualPsbtsResponse); + + /* + PublishAndLogTransfer accepts a fully committed and signed anchor + transaction and publishes it to the Bitcoin network. It also logs the + transfer of the given active and passive assets in the database and ships + any outgoing proofs to the counterparties. + */ + rpc PublishAndLogTransfer (PublishAndLogRequest) + returns (taprpc.SendAssetResponse); + + /* + NextInternalKey derives the next internal key for the given key family and + stores it as an internal key in the database to make sure it is identified + as a local key later on when importing proofs. While an internal key can + also be used as the internal key of a script key, it is recommended to use + the NextScriptKey RPC instead, to make sure the tweaked Taproot output key + is also recognized as a local key. + */ + rpc NextInternalKey (NextInternalKeyRequest) + returns (NextInternalKeyResponse); + + /* + NextScriptKey derives the next script key (and its corresponding internal + key) and stores them both in the database to make sure they are identified + as local keys later on when importing proofs. + */ + rpc NextScriptKey (NextScriptKeyRequest) returns (NextScriptKeyResponse); + + /* + QueryInternalKey returns the key descriptor for the given internal key. + */ + rpc QueryInternalKey (QueryInternalKeyRequest) + returns (QueryInternalKeyResponse); + + /* + QueryScriptKey returns the full script key descriptor for the given tweaked + script key. + */ + rpc QueryScriptKey (QueryScriptKeyRequest) returns (QueryScriptKeyResponse); + + /* tapcli: `proofs proveownership` + ProveAssetOwnership creates an ownership proof embedded in an asset + transition proof. That ownership proof is a signed virtual transaction + spending the asset with a valid witness to prove the prover owns the keys + that can spend the asset. + */ + rpc ProveAssetOwnership (ProveAssetOwnershipRequest) + returns (ProveAssetOwnershipResponse); + + /* tapcli: `proofs verifyownership` + VerifyAssetOwnership verifies the asset ownership proof embedded in the + given transition proof of an asset and returns true if the proof is valid. + */ + rpc VerifyAssetOwnership (VerifyAssetOwnershipRequest) + returns (VerifyAssetOwnershipResponse); + + /* + RemoveUTXOLease removes the lease/lock/reservation of the given managed + UTXO. + */ + rpc RemoveUTXOLease (RemoveUTXOLeaseRequest) + returns (RemoveUTXOLeaseResponse); + + /* + DeclareScriptKey declares a new script key to the wallet. This is useful + when the script key contains scripts, which would mean it wouldn't be + recognized by the wallet automatically. Declaring a script key will make any + assets sent to the script key be recognized as being local assets. + */ + rpc DeclareScriptKey (DeclareScriptKeyRequest) + returns (DeclareScriptKeyResponse); +} + +enum CoinSelectType { + /* + Use the default coin selection type, which currently allows script keys and + key spend paths. + */ + COIN_SELECT_DEFAULT = 0; + + /* + Explicitly only select inputs that are known to be BIP-086 compliant (have + a key-spend path only and no script tree). + */ + COIN_SELECT_BIP86_ONLY = 1; + + /* + Allow the selection of inputs that have a script tree spend path as well as + a key spend path. + */ + COIN_SELECT_SCRIPT_TREES_ALLOWED = 2; +} + +message FundVirtualPsbtRequest { + oneof template { + /* + Use an existing PSBT packet as the template for the funded PSBT. + */ + bytes psbt = 1; + + /* + Use the asset outputs and optional asset inputs from this raw template. + */ + TxTemplate raw = 2; + } + + /* + Specify the type of coins that should be selected. Defaults to allowing both + script trees and BIP-086 compliant inputs. + */ + CoinSelectType coin_select_type = 3; +} + +message FundVirtualPsbtResponse { + /* + The funded but not yet signed virtual PSBT packet. + */ + bytes funded_psbt = 1; + + /* + The index of the added change output or -1 if no change was left over. + */ + int32 change_output_index = 2; + + /* + The list of passive virtual transactions that are anchored in the same BTC + level anchor transaction inputs as the funded "active" asset above. These + assets can be ignored when using the AnchorVirtualPsbts RPC, since they are + retrieved, signed and committed automatically in that method. But the + passive assets have to be included in the CommitVirtualPsbts RPC which is + used when custom BTC level anchor transactions are created. + The main difference to the "active" asset above is that the passive assets + will not get their own entry in the transfer table of the database, since + they are just carried along and not directly affected by the direct user + action. + */ + repeated bytes passive_asset_psbts = 3; +} + +message TxTemplate { + /* + An optional list of inputs to use. Every input must be an asset UTXO known + to the wallet. The sum of all inputs must be greater than or equal to the + sum of all outputs. + + If no inputs are specified, asset coin selection will be performed instead + and inputs of sufficient value will be added to the resulting PSBT. + */ + repeated PrevId inputs = 1; + + /* + A map of all Taproot Asset addresses mapped to the anchor transaction's + output index that should be sent to. + */ + map recipients = 2; +} + +message PrevId { + /* + The bitcoin anchor output on chain that contains the input asset. + */ + taprpc.OutPoint outpoint = 1; + + /* + The asset ID of the previous asset tree. + */ + bytes id = 2; + + /* + The tweaked Taproot output key committing to the possible spending + conditions of the asset. + */ + bytes script_key = 3; +} + +message SignVirtualPsbtRequest { + /* + The PSBT of the virtual transaction that should be signed. The PSBT must + contain all required inputs, outputs, UTXO data and custom fields required + to identify the signing key. + */ + bytes funded_psbt = 1; +} + +message SignVirtualPsbtResponse { + /* + The signed virtual transaction in PSBT format. + */ + bytes signed_psbt = 1; + + /* + The indices of signed inputs. + */ + repeated uint32 signed_inputs = 2; +} + +message AnchorVirtualPsbtsRequest { + /* + The list of virtual transactions that should be merged and committed to in + the BTC level anchor transaction. + */ + repeated bytes virtual_psbts = 1; +} + +message CommitVirtualPsbtsRequest { + /* + The list of virtual transactions that should be mapped to the given BTC + level anchor transaction template. The virtual transactions are expected to + be signed (or use ASSET_VERSION_V1 with segregated witness to allow for + signing after committing) and ready to be committed to the anchor + transaction. + */ + repeated bytes virtual_psbts = 1; + + /* + The list of passive virtual transactions that are anchored in the same BTC + level anchor transaction inputs as the "active" assets above. These can be + obtained by calling FundVirtualPsbt and using the passive assets returned. + The virtual transactions are expected to be signed (or use ASSET_VERSION_V1 + with segregated witness to allow for signing after committing) and ready to + be committed to the anchor transaction. + The main difference to the "active" assets above is that the passive assets + will not get their own entry in the transfer table of the database, since + they are just carried along and not directly affected by the direct user + action. + */ + repeated bytes passive_asset_psbts = 2; + + /* + The template of the BTC level anchor transaction that the virtual + transactions should be mapped to. The template is expected to already + contain all asset related inputs and outputs corresponding to the virtual + transactions given above. This can be achieved by using + tapfreighter.PrepareAnchoringTemplate for example. + */ + bytes anchor_psbt = 3; + + oneof anchor_change_output { + /* + Use the existing output within the anchor PSBT with the specified + index as the change output. Any leftover change will be added to the + already specified amount of that output. To add a new change output to + the PSBT, set the "add" field below instead. + */ + int32 existing_output_index = 4; + + /* + Add a new P2TR change output to the PSBT if required. + */ + bool add = 5; + } + + oneof fees { + /* + The target number of blocks that the transaction should be confirmed in. + */ + uint32 target_conf = 6; + + /* + The fee rate, expressed in sat/vbyte, that should be used to fund the + BTC level anchor transaction. + */ + uint64 sat_per_vbyte = 7; + } +} + +message CommitVirtualPsbtsResponse { + /* + The funded BTC level anchor transaction with all outputs updated to commit + to the virtual transactions given. The transaction is ready to be signed, + unless some of the asset inputs don't belong to this daemon, in which case + the anchor input derivation info must be added to those inputs first. + */ + bytes anchor_psbt = 1; + + /* + The updated virtual transactions that now contain the state transition + proofs for being committed to the BTC level anchor transaction above. If the + assets in the virtual transaction outputs are ASSET_VERSION_V1 and not yet + signed, then the proofs need to be updated to include the witness before + they become fully valid. + */ + repeated bytes virtual_psbts = 2; + + /* + The updated passive virtual transactions that were committed to the same BTC + level anchor transaction as the "active" virtual transactions given. If the + assets in the virtual transaction outputs are ASSET_VERSION_V1 and not yet + signed, then the proofs need to be updated to include the witness before + they become fully valid. + */ + repeated bytes passive_asset_psbts = 4; + + /* + The index of the (added) change output or -1 if no change was left over. + */ + int32 change_output_index = 5; + + /* + The list of UTXO lock leases that were acquired for the inputs in the funded + PSBT packet from lnd. Only inputs added to the PSBT by this RPC are locked, + inputs that were already present in the PSBT are not locked. + */ + repeated taprpc.OutPoint lnd_locked_utxos = 6; +} + +message PublishAndLogRequest { + /* + The funded BTC level anchor transaction with all outputs updated to commit + to the virtual transactions given. The transaction is ready to be signed, + unless some of the asset inputs don't belong to this daemon, in which case + the anchor input derivation info must be added to those inputs first. + */ + bytes anchor_psbt = 1; + + /* + The updated virtual transactions that contain the state transition proofs + of being committed to the BTC level anchor transaction above. + */ + repeated bytes virtual_psbts = 2; + + /* + The updated passive virtual transactions that contain the state transition + proofs of being committed to the BTC level anchor transaction above. + */ + repeated bytes passive_asset_psbts = 3; + + /* + The index of the (added) change output or -1 if no change was left over. + */ + int32 change_output_index = 4; + + /* + The list of UTXO lock leases that were acquired for the inputs in the funded + PSBT packet from lnd. Only inputs added to the PSBT by this RPC are locked, + inputs that were already present in the PSBT are not locked. + */ + repeated taprpc.OutPoint lnd_locked_utxos = 5; +} + +message NextInternalKeyRequest { + uint32 key_family = 1; +} + +message NextInternalKeyResponse { + taprpc.KeyDescriptor internal_key = 1; +} + +message NextScriptKeyRequest { + uint32 key_family = 1; +} + +message NextScriptKeyResponse { + taprpc.ScriptKey script_key = 1; +} + +message QueryInternalKeyRequest { + // The internal key to look for. This can either be the 32-byte x-only raw + // internal key or the 33-byte raw internal key with the parity byte. + bytes internal_key = 1; +} + +message QueryInternalKeyResponse { + taprpc.KeyDescriptor internal_key = 1; +} + +message QueryScriptKeyRequest { + // The tweaked script key to look for. This can either be the 32-byte + // x-only tweaked script key or the 33-byte tweaked script key with the + // parity byte. + bytes tweaked_script_key = 1; +} + +message QueryScriptKeyResponse { + taprpc.ScriptKey script_key = 1; +} + +message ProveAssetOwnershipRequest { + bytes asset_id = 1; + + bytes script_key = 2; + + taprpc.OutPoint outpoint = 3; + + // An optional 32-byte challenge that may be used to bind the generated + // proof. This challenge needs to be also presented on the + // VerifyAssetOwnership RPC in order to check the proof against it. + bytes challenge = 4; +} + +message ProveAssetOwnershipResponse { + bytes proof_with_witness = 1; +} + +message VerifyAssetOwnershipRequest { + bytes proof_with_witness = 1; + + // An optional 32-byte challenge that may be used to check the ownership + // proof against. This challenge must match the one that the prover used + // on the ProveAssetOwnership RPC. + bytes challenge = 2; +} + +message VerifyAssetOwnershipResponse { + bool valid_proof = 1; + + // The outpoint the proof commits to. + taprpc.OutPoint outpoint = 2; + + // The outpoint in the human-readable form "hash:index". + string outpoint_str = 3; + + // The block hash the output is part of. + bytes block_hash = 4; + + // The block hash as hexadecimal string of the byte-reversed hash. + string block_hash_str = 5; + + // The block height of the block the output is part of. + uint32 block_height = 6; +} + +message RemoveUTXOLeaseRequest { + // The outpoint of the UTXO to remove the lease for. + taprpc.OutPoint outpoint = 1; +} + +message RemoveUTXOLeaseResponse { +} + +message DeclareScriptKeyRequest { + taprpc.ScriptKey script_key = 1; +} + +message DeclareScriptKeyResponse { + taprpc.ScriptKey script_key = 1; +} \ No newline at end of file diff --git a/protos/tapd/v0.5.0-rc2/mintrpc/mint.proto b/protos/tapd/v0.5.0-rc2/mintrpc/mint.proto new file mode 100644 index 0000000..abc446b --- /dev/null +++ b/protos/tapd/v0.5.0-rc2/mintrpc/mint.proto @@ -0,0 +1,411 @@ +syntax = "proto3"; + +import "taprootassets.proto"; + +package mintrpc; + +option go_package = "github.com/lightninglabs/taproot-assets/taprpc/mintrpc"; + +service Mint { + /* tapcli: `assets mint` + MintAsset will attempt to mint the set of assets (async by default to + ensure proper batching) specified in the request. The pending batch is + returned that shows the other pending assets that are part of the next + batch. This call will block until the operation succeeds (asset is staged + in the batch) or fails. + */ + rpc MintAsset (MintAssetRequest) returns (MintAssetResponse); + + /* tapcli `assets mint fund` + FundBatch will attempt to fund the current pending batch with a genesis + input, or create a new funded batch if no batch exists yet. This RPC is only + needed if a custom witness is needed to finalize the batch. Otherwise, + FinalizeBatch can be called directly. + */ + rpc FundBatch (FundBatchRequest) returns (FundBatchResponse); + + /* tapcli `assets mint seal` + SealBatch will attempt to seal the current pending batch by creating and + validating asset group witness for all assets in the batch. If a witness + is not provided, a signature will be derived to serve as the witness. This + RPC is only needed if any assets in the batch have a custom asset group key + that require an external signer. Otherwise, FinalizeBatch can be called + directly. + */ + rpc SealBatch (SealBatchRequest) returns (SealBatchResponse); + + /* tapcli: `assets mint finalize` + FinalizeBatch will attempt to finalize the current pending batch. + */ + rpc FinalizeBatch (FinalizeBatchRequest) returns (FinalizeBatchResponse); + + /* tapcli: `assets mint cancel` + CancelBatch will attempt to cancel the current pending batch. + */ + rpc CancelBatch (CancelBatchRequest) returns (CancelBatchResponse); + + /* tapcli: `assets mint batches` + ListBatches lists the set of batches submitted to the daemon, including + pending and cancelled batches. + */ + rpc ListBatches (ListBatchRequest) returns (ListBatchResponse); + + /* tapcli: `events mint` + SubscribeMintEvents allows a caller to subscribe to mint events for asset + creation batches. + */ + rpc SubscribeMintEvents (SubscribeMintEventsRequest) + returns (stream MintEvent); +} + +message PendingAsset { + // The version of asset to mint. + taprpc.AssetVersion asset_version = 1; + + // The type of the asset to be created. + taprpc.AssetType asset_type = 2; + + // The name, or "tag" of the asset. This will affect the final asset ID. + string name = 3; + + /* + A blob that resents metadata related to the asset. This will affect the + final asset ID. + */ + taprpc.AssetMeta asset_meta = 4; + + /* + The total amount of units of the new asset that should be created. If the + AssetType is Collectible, then this field cannot be set. + */ + uint64 amount = 5; + + /* + If true, then the asset will be created with a new group key, which allows + for future asset issuance. + */ + bool new_grouped_asset = 6; + + // The specific existing group key this asset should be minted with. + bytes group_key = 7; + + /* + The name of the asset in the batch that will anchor a new asset group. + This asset will be minted with the same group key as the anchor asset. + */ + string group_anchor = 8; + + /* + The optional key that will be used as the internal key for an asset group + created with this asset. + */ + taprpc.KeyDescriptor group_internal_key = 9; + + /* + The optional root of a tapscript tree that will be used when constructing a + new asset group key. This enables future issuance authorized with a script + witness. + */ + bytes group_tapscript_root = 10; + + /* + The optional script key to use for the new asset. If no script key is given, + a BIP-86 key will be derived from the underlying wallet. + */ + taprpc.ScriptKey script_key = 11; +} + +message UnsealedAsset { + // The pending asset with an unsealed asset group. + PendingAsset asset = 1; + + // The group key request for the asset. + taprpc.GroupKeyRequest group_key_request = 2; + + // The group virtual transaction for the asset. + taprpc.GroupVirtualTx group_virtual_tx = 3; +} + +message MintAsset { + // The version of asset to mint. + taprpc.AssetVersion asset_version = 1; + + // The type of the asset to be created. + taprpc.AssetType asset_type = 2; + + // The name, or "tag" of the asset. This will affect the final asset ID. + string name = 3; + + /* + A blob that resents metadata related to the asset. This will affect the + final asset ID. + */ + taprpc.AssetMeta asset_meta = 4; + + /* + The total amount of units of the new asset that should be created. If the + AssetType is Collectible, then this field cannot be set. + */ + uint64 amount = 5; + + /* + If true, then the asset will be created with a group key, which allows for + future asset issuance. + */ + bool new_grouped_asset = 6; + + /* + If true, then a group key or group anchor can be set to mint this asset into + an existing asset group. + */ + bool grouped_asset = 7; + + // The specific existing group key this asset should be minted with. + bytes group_key = 8; + + /* + The name of the asset in the batch that will anchor a new asset group. + This asset will be minted with the same group key as the anchor asset. + */ + string group_anchor = 9; + + /* + The optional key that will be used as the internal key for an asset group + created with this asset. + */ + taprpc.KeyDescriptor group_internal_key = 10; + + /* + The optional root of a tapscript tree that will be used when constructing a + new asset group key. This enables future issuance authorized with a script + witness. + */ + bytes group_tapscript_root = 11; + + /* + The optional script key to use for the new asset. If no script key is given, + a BIP-86 key will be derived from the underlying wallet. + */ + taprpc.ScriptKey script_key = 12; + + /* + Decimal display dictates the number of decimal places to shift the amount to + the left converting from Taproot Asset integer representation to a + UX-recognizable fractional quantity. + + For example, if the decimal_display value is 2 and there's 100 of those + assets, then a wallet would display the amount as "1.00". This field is + intended as information for wallets that display balances and has no impact + on the behavior of the daemon or any other part of the protocol. This value + is encoded in the MetaData field as a JSON field, therefore it is only + compatible with assets that have a JSON MetaData field. + */ + uint32 decimal_display = 13; +} + +message MintAssetRequest { + /* + The asset to be minted. + */ + MintAsset asset = 1; + + /* + If true, then the assets currently in the batch won't be returned in the + response. This is mainly to avoid a lot of data being transmitted and + possibly printed on the command line in the case of a very large batch. + */ + bool short_response = 2; +} + +message MintAssetResponse { + // The pending batch the asset was added to. + MintingBatch pending_batch = 1; +} + +message MintingBatch { + /* + A public key serialized in compressed format that can be used to uniquely + identify a pending minting batch. Responses that share the same key will be + batched into the same minting transaction. + */ + bytes batch_key = 1; + + /* + The transaction ID of the batch. Only populated if the batch has been + committed. + */ + string batch_txid = 2; + + // The state of the batch. + BatchState state = 3; + + // The assets that are part of the batch. + repeated PendingAsset assets = 4; + + // The time the batch was created as a Unix timestamp (in seconds). + int64 created_at = 5; + + // The current height of the block chain at the time of the batch creation. + uint32 height_hint = 6; + + // The genesis transaction as a PSBT packet. Only populated if the batch has + // been committed. + bytes batch_psbt = 7; +} + +message VerboseBatch { + // The minting batch, without any assets. + MintingBatch batch = 1; + + // The assets that are part of the batch. + repeated UnsealedAsset unsealed_assets = 2; +} + +enum BatchState { + BATCH_STATE_UNKNOWN = 0; + BATCH_STATE_PENDING = 1; + BATCH_STATE_FROZEN = 2; + BATCH_STATE_COMMITTED = 3; + BATCH_STATE_BROADCAST = 4; + BATCH_STATE_CONFIRMED = 5; + BATCH_STATE_FINALIZED = 6; + BATCH_STATE_SEEDLING_CANCELLED = 7; + BATCH_STATE_SPROUT_CANCELLED = 8; +} + +message FundBatchRequest { + /* + If true, then the assets currently in the batch won't be returned in the + response. This is mainly to avoid a lot of data being transmitted and + possibly printed on the command line in the case of a very large batch. + */ + bool short_response = 1; + + // The optional fee rate to use for the minting transaction, in sat/kw. + uint32 fee_rate = 2; + + /* + The optional tapscript sibling that will be used when deriving the genesis + output for the batch. This sibling is a tapscript tree, which allows the + minter to encumber future transfers of assets in the batch with Tapscript. + */ + oneof batch_sibling { + /* + An ordered list of TapLeafs, which will be used to construct a + Tapscript tree. + */ + taprpc.TapscriptFullTree full_tree = 3; + + // A TapBranch that represents a Tapscript tree managed externally. + taprpc.TapBranch branch = 4; + } +} + +message FundBatchResponse { + // The funded batch. + MintingBatch batch = 1; +} + +message SealBatchRequest { + /* + If true, then the assets currently in the batch won't be returned in the + response. This is mainly to avoid a lot of data being transmitted and + possibly printed on the command line in the case of a very large batch. + */ + bool short_response = 1; + + // The assetID, witness pairs that authorize asset membership in a group. + repeated taprpc.GroupWitness group_witnesses = 2; +} + +message SealBatchResponse { + // The sealed batch. + MintingBatch batch = 1; +} + +message FinalizeBatchRequest { + /* + If true, then the assets currently in the batch won't be returned in the + response. This is mainly to avoid a lot of data being transmitted and + possibly printed on the command line in the case of a very large batch. + */ + bool short_response = 1; + + // The optional fee rate to use for the minting transaction, in sat/kw. + uint32 fee_rate = 2; + + /* + The optional tapscript sibling that will be used when deriving the genesis + output for the batch. This sibling is a tapscript tree, which allows the + minter to encumber future transfers of assets in the batch with Tapscript. + */ + oneof batch_sibling { + /* + An ordered list of TapLeafs, which will be used to construct a + Tapscript tree. + */ + taprpc.TapscriptFullTree full_tree = 3; + + // A TapBranch that represents a Tapscript tree managed externally. + taprpc.TapBranch branch = 4; + } +} + +message FinalizeBatchResponse { + // The finalized batch. + MintingBatch batch = 1; +} + +message CancelBatchRequest { +} + +message CancelBatchResponse { + // The internal public key of the batch. + bytes batch_key = 1; +} + +message ListBatchRequest { + // The optional batch key of the batch to list. + oneof filter { + // The optional batch key of the batch to list, specified as raw bytes + // (gRPC only). + bytes batch_key = 1; + + // The optional batch key of the batch to list, specified as a hex + // encoded string (use this for REST). + string batch_key_str = 2; + } + + // If true, pending asset group information will be shown for the pending + // batch. + bool verbose = 3; +} + +message ListBatchResponse { + repeated VerboseBatch batches = 1; +} + +message SubscribeMintEventsRequest { + /* + If true, then the assets currently in the batch won't be returned in the + event's batch. This is mainly to avoid a lot of data being transmitted and + possibly printed on the command line in the case of a very large batch. + */ + bool short_response = 1; +} + +message MintEvent { + // Execute timestamp (Unix timestamp in microseconds). + int64 timestamp = 1; + + // The last state of the batch that was successfully executed. If error + // below is set, then the batch_state is the state that lead to the error + // during its execution. + BatchState batch_state = 2; + + // The batch that the event is for. + MintingBatch batch = 3; + + // An optional error, indicating that executing the batch_state failed. + string error = 4; +} diff --git a/protos/tapd/v0.5.0-rc2/priceoraclerpc/price_oracle.proto b/protos/tapd/v0.5.0-rc2/priceoraclerpc/price_oracle.proto new file mode 100644 index 0000000..fd0ab1f --- /dev/null +++ b/protos/tapd/v0.5.0-rc2/priceoraclerpc/price_oracle.proto @@ -0,0 +1,159 @@ +syntax = "proto3"; + +package priceoraclerpc; + +option go_package = "github.com/lightninglabs/taproot-assets/taprpc/priceoraclerpc"; + +service PriceOracle { + /* + QueryAssetRates retrieves the exchange rate between a tap asset and BTC for + a specified transaction type, subject asset, and payment asset. The asset + rate represents the number of tap asset units per BTC. + */ + rpc QueryAssetRates (QueryAssetRatesRequest) + returns (QueryAssetRatesResponse); +} + +// TransactionType is an enum representing the type of transaction. +enum TransactionType { + // PURCHASE indicates a purchase transaction. + PURCHASE = 0; + + // SALE indicates a sale transaction. + SALE = 1; +} + +// FixedPoint is a scaled integer representation of a fractional number. +// +// This type consists of two integer fields: a coefficient and a scale. +// Using this format enables precise and consistent representation of fractional +// numbers while avoiding floating-point data types, which are prone to +// precision errors. +// +// The relationship between the fractional representation and its fixed-point +// representation is expressed as: +// ``` +// V = F_c / (10^F_s) +// ``` +// where: +// +// * `V` is the fractional value. +// +// * `F_c` is the coefficient component of the fixed-point representation. It is +// the scaled-up fractional value represented as an integer. +// +// * `F_s` is the scale component. It is an integer specifying how +// many decimal places `F_c` should be divided by to obtain the fractional +// representation. +message FixedPoint { + // The coefficient is the fractional value scaled-up as an integer. This + // integer is represented as a string as it may be too large to fit in a + // uint64. + string coefficient = 1; + + // The scale is the component that determines how many decimal places + // the coefficient should be divided by to obtain the fractional value. + uint32 scale = 2; +} + +// AssetRates represents the exchange rates for subject and payment assets +// relative to BTC, expressed as fixed-point numbers. It includes the rates +// for both assets and an expiration timestamp indicating when the rates +// are no longer valid. +message AssetRates { + // subjectAssetRate is the number of subject asset units per BTC represented + // as a fixed-point number. This field is also commonly referred to as the + // subject asset to BTC (conversion) rate. When the subject asset is BTC, + // this field should be set to 100 billion, as one BTC is equivalent to 100 + // billion msats. + FixedPoint subjectAssetRate = 1; + + // paymentAssetRate is the number of payment asset units per BTC represented + // as a fixed-point number. This field is also commonly referred to as the + // payment asset to BTC (conversion) rate. When the payment asset is BTC, + // this field should be set to 100 billion, as one BTC is equivalent to 100 + // billion msats. + FixedPoint paymentAssetRate = 2; + + // expiry_timestamp is the Unix timestamp in seconds after which the asset + // rates are no longer valid. + uint64 expiry_timestamp = 3; +} + +// AssetSpecifier is a union type for specifying an asset by either its asset ID +// or group key. +message AssetSpecifier { + oneof id { + // The 32-byte asset ID specified as raw bytes (gRPC only). + bytes asset_id = 1; + + // The 32-byte asset ID encoded as a hex string (use this for REST). + string asset_id_str = 2; + + // The 32-byte asset group key specified as raw bytes (gRPC only). + bytes group_key = 3; + + // The 32-byte asset group key encoded as hex string (use this for + // REST). + string group_key_str = 4; + } +} + +// QueryAssetRatesRequest specifies the parameters for querying asset exchange +// rates in a transaction. It includes the transaction type, details about the +// subject and payment assets, and an optional hint for expected asset rates. +message QueryAssetRatesRequest { + // transaction_type indicates whether the transaction is a purchase or a + // sale. + TransactionType transaction_type = 1; + + // subject_asset is the asset to be priced for purchase or sale. + AssetSpecifier subject_asset = 2; + + // subject_asset_max_amount is the maximum amount of the subject asset that + // could be involved in the transaction. + uint64 subject_asset_max_amount = 3; + + // payment_asset is the asset used for purchasing or receiving from a sale. + // + // NOTE: An asset ID of all zeros indicates that the payment asset is BTC. + // In this case, the asset rate will be given as milli-satoshi per asset + // unit + AssetSpecifier payment_asset = 4; + + // payment_asset_max_amount is the maximum amount of the payment asset that + // could be involved in the transaction. This field is optional. If set to + // zero, it is considered unset. + uint64 payment_asset_max_amount = 5; + + // asset_rates_hint is an optional suggestion of asset rates for the + // transaction, intended to provide guidance on expected pricing. + AssetRates asset_rates_hint = 6; +} + +// QueryAssetRatesOkResponse is the successful response to a +// QueryAssetRates call. +message QueryAssetRatesOkResponse { + // asset_rates is the asset exchange rates for the transaction. + AssetRates asset_rates = 1; +} + +// QueryAssetRatesErrResponse is the error response to a QueryAssetRates call. +message QueryAssetRatesErrResponse { + // error is the error message. + string message = 1; + + // code is the error code. + uint32 code = 2; +} + +// QueryAssetRatesResponse is the response from a QueryAssetRates RPC call. +message QueryAssetRatesResponse { + oneof result { + // ok is the successful response to the query. + QueryAssetRatesOkResponse ok = 1; + + // error is the error response to the query. + QueryAssetRatesErrResponse error = 2; + } +} diff --git a/protos/tapd/v0.5.0-rc2/rfqrpc/rfq.proto b/protos/tapd/v0.5.0-rc2/rfqrpc/rfq.proto new file mode 100644 index 0000000..768c893 --- /dev/null +++ b/protos/tapd/v0.5.0-rc2/rfqrpc/rfq.proto @@ -0,0 +1,372 @@ +syntax = "proto3"; + +package rfqrpc; + +option go_package = "github.com/lightninglabs/taproot-assets/taprpc/rfqrpc"; + +service Rfq { + /* tapcli: `rfq buyorder` + AddAssetBuyOrder is used to add a buy order for a specific asset. If a buy + order already exists for the asset, it will be updated. + + A buy order instructs the RFQ (Request For Quote) system to request a quote + from a peer for the acquisition of an asset. + + The normal use of a buy order is as follows: + 1. Alice, operating a wallet node, wants to receive a Tap asset as payment + by issuing a Lightning invoice. + 2. Alice has an asset channel established with Bob's edge node. + 3. Before issuing the invoice, Alice needs to agree on an exchange rate with + Bob, who will facilitate the asset transfer. + 4. To obtain the best exchange rate, Alice creates a buy order specifying + the desired asset. + 5. Alice's RFQ subsystem processes the buy order and sends buy requests to + relevant peers to find the best rate. In this example, Bob is the only + available peer. + 6. Once Bob provides a satisfactory quote, Alice accepts it. + 7. Alice issues the Lightning invoice, which Charlie will pay. + 8. Instead of paying Alice directly, Charlie pays Bob. + 9. Bob then forwards the agreed amount of the Tap asset to Alice over their + asset channel. + */ + rpc AddAssetBuyOrder (AddAssetBuyOrderRequest) + returns (AddAssetBuyOrderResponse); + + /* tapcli: `rfq sellorder` + AddAssetSellOrder is used to add a sell order for a specific asset. If a + sell order already exists for the asset, it will be updated. + */ + rpc AddAssetSellOrder (AddAssetSellOrderRequest) + returns (AddAssetSellOrderResponse); + + /* tapcli: `rfq selloffer` + AddAssetSellOffer is used to add a sell offer for a specific asset. If a + sell offer already exists for the asset, it will be updated. + */ + rpc AddAssetSellOffer (AddAssetSellOfferRequest) + returns (AddAssetSellOfferResponse); + + /* tapcli: `rfq buyoffer` + AddAssetBuyOffer is used to add a buy offer for a specific asset. If a + buy offer already exists for the asset, it will be updated. + + A buy offer is used by the node to selectively accept or reject incoming + asset sell quote requests before price is considered. + */ + rpc AddAssetBuyOffer (AddAssetBuyOfferRequest) + returns (AddAssetBuyOfferResponse); + + /* tapcli: `rfq acceptedquotes` + QueryPeerAcceptedQuotes is used to query for quotes that were requested by + our node and have been accepted our peers. + */ + rpc QueryPeerAcceptedQuotes (QueryPeerAcceptedQuotesRequest) + returns (QueryPeerAcceptedQuotesResponse); + + /* + SubscribeRfqEventNtfns is used to subscribe to RFQ events. + */ + rpc SubscribeRfqEventNtfns (SubscribeRfqEventNtfnsRequest) + returns (stream RfqEvent); +} + +message AssetSpecifier { + oneof id { + // The 32-byte asset ID specified as raw bytes (gRPC only). + bytes asset_id = 1; + + // The 32-byte asset ID encoded as a hex string (use this for REST). + string asset_id_str = 2; + + // The 32-byte asset group key specified as raw bytes (gRPC only). + bytes group_key = 3; + + // The 32-byte asset group key encoded as hex string (use this for + // REST). + string group_key_str = 4; + } +} + +// FixedPoint is a scaled integer representation of a fractional number. +// +// This type consists of two integer fields: a coefficient and a scale. +// Using this format enables precise and consistent representation of fractional +// numbers while avoiding floating-point data types, which are prone to +// precision errors. +// +// The relationship between the fractional representation and its fixed-point +// representation is expressed as: +// ``` +// V = F_c / (10^F_s) +// ``` +// where: +// +// * `V` is the fractional value. +// +// * `F_c` is the coefficient component of the fixed-point representation. It is +// the scaled-up fractional value represented as an integer. +// +// * `F_s` is the scale component. It is an integer specifying how +// many decimal places `F_c` should be divided by to obtain the fractional +// representation. +message FixedPoint { + // The coefficient is the fractional value scaled-up as an integer. This + // integer is represented as a string as it may be too large to fit in a + // uint64. + string coefficient = 1; + + // The scale is the component that determines how many decimal places + // the coefficient should be divided by to obtain the fractional value. + uint32 scale = 2; +} + +message AddAssetBuyOrderRequest { + // asset_specifier is the subject asset. + AssetSpecifier asset_specifier = 1; + + // The maximum amount of the asset that the provider must be willing to + // offer. + uint64 asset_max_amt = 2; + + // The unix timestamp in seconds after which the order is no longer valid. + uint64 expiry = 3; + + // peer_pub_key is an optional field for specifying the public key of the + // intended recipient peer for the order. + bytes peer_pub_key = 4; + + // timeout_seconds is the number of seconds to wait for the peer to respond + // with an accepted quote (or a rejection). + uint32 timeout_seconds = 5; + + // If set, the check if a channel with the given asset exists with the peer + // will be skipped. An active channel with the peer is still required for + // the RFQ negotiation to work. This flag shouldn't be set outside of test + // scenarios. + bool skip_asset_channel_check = 6; +} + +message AddAssetBuyOrderResponse { + oneof response { + // accepted_quote holds the quote received from the peer as a response + // to our quote request. + PeerAcceptedBuyQuote accepted_quote = 1; + + // invalid_quote is returned if the quote response received from the + // peer was invalid or insufficient. + InvalidQuoteResponse invalid_quote = 2; + + // rejected_quote is returned if the quote request was rejected by the + // peer. + RejectedQuoteResponse rejected_quote = 3; + } +} + +message AddAssetSellOrderRequest { + // asset_specifier is the subject asset. + AssetSpecifier asset_specifier = 1; + + // The maximum msat amount that the responding peer must agree to pay + // (units: millisats). + uint64 payment_max_amt = 2; + + // The unix timestamp in seconds after which the order is no longer valid. + uint64 expiry = 3; + + // peer_pub_key is an optional field for specifying the public key of the + // intended recipient peer for the order. + bytes peer_pub_key = 4; + + // timeout_seconds is the number of seconds to wait for the peer to respond + // with an accepted quote (or a rejection). + uint32 timeout_seconds = 5; + + // If set, the check if a channel with the given asset exists with the peer + // will be skipped. An active channel with the peer is still required for + // the RFQ negotiation to work. This flag shouldn't be set outside of test + // scenarios. + bool skip_asset_channel_check = 6; +} + +message AddAssetSellOrderResponse { + oneof response { + // accepted_quote holds the quote received from the peer as a response + // to our quote request. + PeerAcceptedSellQuote accepted_quote = 1; + + // invalid_quote is returned if the quote response received from the + // peer was invalid or insufficient. + InvalidQuoteResponse invalid_quote = 2; + + // rejected_quote is returned if the quote request was rejected by the + // peer. + RejectedQuoteResponse rejected_quote = 3; + } +} + +message AddAssetSellOfferRequest { + // asset_specifier is the subject asset. + AssetSpecifier asset_specifier = 1; + + // max_units is the maximum amount of the asset to sell. + uint64 max_units = 2; +} + +message AddAssetSellOfferResponse { +} + +message AddAssetBuyOfferRequest { + // asset_specifier is the subject asset. + AssetSpecifier asset_specifier = 1; + + // max_units is the maximum amount of the asset to buy. + uint64 max_units = 2; +} + +message AddAssetBuyOfferResponse { +} + +message QueryPeerAcceptedQuotesRequest { +} + +message PeerAcceptedBuyQuote { + // Quote counterparty peer. + string peer = 1; + + // The unique identifier of the quote request. + bytes id = 2; + + // scid is the short channel ID of the channel over which the payment for + // the quote should be made. + uint64 scid = 3; + + // asset_amount is the amount of the subject asset. + uint64 asset_amount = 4; + + // ask_asset_rate is the asset to BTC conversion rate represented as a + // fixed-point number. + FixedPoint ask_asset_rate = 5; + + // The unix timestamp in seconds after which the quote is no longer valid. + uint64 expiry = 6; +} + +message PeerAcceptedSellQuote { + // Quote counterparty peer. + string peer = 1; + + // The unique identifier of the quote request. + bytes id = 2; + + // scid is the short channel ID of the channel over which the payment for + // the quote should be made. + uint64 scid = 3; + + // asset_amount is the amount of the subject asset. + uint64 asset_amount = 4; + + // bid_asset_rate is the asset to BTC conversion rate represented as a + // fixed-point number. + FixedPoint bid_asset_rate = 5; + + // The unix timestamp in seconds after which the quote is no longer valid. + uint64 expiry = 6; +} + +// QuoteRespStatus is an enum that represents the status of a quote response. +enum QuoteRespStatus { + // INVALID_ASSET_RATES indicates that at least one asset rate in the + // quote response is invalid. + INVALID_ASSET_RATES = 0; + + // INVALID_EXPIRY indicates that the expiry in the quote response is + // invalid. + INVALID_EXPIRY = 1; + + // PRICE_ORACLE_QUERY_ERR indicates that an error occurred when querying the + // price oracle whilst evaluating the quote response. + PRICE_ORACLE_QUERY_ERR = 2; +} + +// InvalidQuoteResponse is a message that is returned when a quote response is +// invalid or insufficient. +message InvalidQuoteResponse { + // status is the status of the quote response. + QuoteRespStatus status = 1; + + // peer is the quote counterparty peer. + string peer = 2; + + // id is the unique identifier of the quote request. + bytes id = 3; +} + +// RejectedQuoteResponse is a message that is returned when a quote request is +// rejected by the peer. +message RejectedQuoteResponse { + // peer is the quote counterparty peer. + string peer = 1; + + // id is the unique identifier of the quote request. + bytes id = 2; + + // error_message is a human-readable error message. + string error_message = 3; + + // error_code is a machine-readable error code. + uint32 error_code = 4; +} + +message QueryPeerAcceptedQuotesResponse { + // buy_quotes is a list of asset buy quotes which were requested by our + // node and have been accepted by our peers. + repeated PeerAcceptedBuyQuote buy_quotes = 1; + + // sell_quotes is a list of asset sell quotes which were requested by our + // node and have been accepted by our peers. + repeated PeerAcceptedSellQuote sell_quotes = 2; +} + +message SubscribeRfqEventNtfnsRequest { +} + +message PeerAcceptedBuyQuoteEvent { + // Unix timestamp in microseconds. + uint64 timestamp = 1; + + // The asset buy quote that was accepted by out peer. + PeerAcceptedBuyQuote peer_accepted_buy_quote = 2; +} + +message PeerAcceptedSellQuoteEvent { + // Unix timestamp in microseconds. + uint64 timestamp = 1; + + // The asset sell quote that was accepted by out peer. + PeerAcceptedSellQuote peer_accepted_sell_quote = 2; +} + +message AcceptHtlcEvent { + // Unix timestamp in microseconds. + uint64 timestamp = 1; + + // scid is the short channel ID of the channel over which the payment for + // the quote is made. + uint64 scid = 2; +} + +message RfqEvent { + oneof event { + // peer_accepted_buy_quote is an event that is emitted when a peer + // accepted (incoming) asset buy quote message is received. + PeerAcceptedBuyQuoteEvent peer_accepted_buy_quote = 1; + + // peer_accepted_sell_offer is an event that is emitted when a peer + // accepted (incoming) asset sell quote message is received. + PeerAcceptedSellQuoteEvent peer_accepted_sell_quote = 2; + + // accept_htlc is an event that is sent when a HTLC is accepted by the + // RFQ service. + AcceptHtlcEvent accept_htlc = 3; + } +} diff --git a/protos/tapd/v0.5.0-rc2/tapchannelrpc/tapchannel.proto b/protos/tapd/v0.5.0-rc2/tapchannelrpc/tapchannel.proto new file mode 100644 index 0000000..84f79fe --- /dev/null +++ b/protos/tapd/v0.5.0-rc2/tapchannelrpc/tapchannel.proto @@ -0,0 +1,183 @@ +syntax = "proto3"; + +package tapchannelrpc; + +option go_package = "github.com/lightninglabs/taproot-assets/taprpc/tapchannelrpc"; + +import "rfqrpc/rfq.proto"; +import "lightning.proto"; +import "routerrpc/router.proto"; + +service TaprootAssetChannels { + /* + FundChannel initiates the channel funding negotiation with a peer for the + creation of a channel that contains a specified amount of a given asset. + */ + rpc FundChannel (FundChannelRequest) returns (FundChannelResponse); + + /* + EncodeCustomRecords allows RPC users to encode Taproot Asset channel related + data into the TLV format that is used in the custom records of the lnd + payment or other channel related RPCs. This RPC is completely stateless and + does not perform any checks on the data provided, other than pure format + validation. + */ + rpc EncodeCustomRecords (EncodeCustomRecordsRequest) + returns (EncodeCustomRecordsResponse); + + /* + SendPayment is a wrapper around lnd's routerrpc.SendPaymentV2 RPC method + with asset specific parameters. It allows RPC users to send asset keysend + payments (direct payments) or payments to an invoice with a specified asset + amount. + */ + rpc SendPayment (SendPaymentRequest) returns (stream SendPaymentResponse); + + /* + AddInvoice is a wrapper around lnd's lnrpc.AddInvoice method with asset + specific parameters. It allows RPC users to create invoices that correspond + to the specified asset amount. + */ + rpc AddInvoice (AddInvoiceRequest) returns (AddInvoiceResponse); +} + +message FundChannelRequest { + // The asset amount to fund the channel with. The BTC amount is fixed and + // cannot be customized (for now). + uint64 asset_amount = 1; + + // The asset ID to use for the channel funding. + bytes asset_id = 2; + + // The public key of the peer to open the channel with. Must already be + // connected to this peer. + bytes peer_pubkey = 3; + + // The channel funding fee rate in sat/vByte. + uint32 fee_rate_sat_per_vbyte = 4; + + // The number of satoshis to give the remote side as part of the initial + // commitment state. This is equivalent to first opening a channel and then + // sending the remote party funds, but all done in one step. Therefore, this + // is equivalent to a donation to the remote party, unless they reimburse + // the funds in another way (outside the protocol). + int64 push_sat = 5; +} + +message FundChannelResponse { + // The channel funding transaction ID. + string txid = 1; + + // The index of the channel funding output in the funding transaction. + int32 output_index = 2; +} + +message RouterSendPaymentData { + // The string encoded asset ID to amount mapping. Instructs the router to + // use these assets in the given amounts for the payment. Can be empty for + // a payment of an invoice, if the RFQ ID is set instead. + map asset_amounts = 1; + + // The RFQ ID to use for the payment. Can be empty for a direct keysend + // payment that doesn't involve any conversion (and thus no RFQ). + bytes rfq_id = 2; +} + +message EncodeCustomRecordsRequest { + oneof input { + RouterSendPaymentData router_send_payment = 1; + } +} + +message EncodeCustomRecordsResponse { + // The encoded custom records in TLV format. + map custom_records = 1; +} + +message SendPaymentRequest { + // The asset ID to use for the payment. This must be set for both invoice + // and keysend payments, unless RFQ negotiation was already done beforehand + // and payment_request.first_hop_custom_records already contains valid RFQ + // data. + bytes asset_id = 1; + + // The asset amount to send in a keysend payment. This amount is ignored for + // invoice payments as the asset amount is negotiated through RFQ with the + // peer, depending on the invoice amount. This can also be left unset if RFQ + // negotiation was already done beforehand and + // payment_request.first_hop_custom_records already contains valid RFQ data. + uint64 asset_amount = 2; + + // The node identity public key of the peer to ask for a quote for sending + // out the assets and converting them to satoshis. This must be specified if + // there are multiple channels with the given asset ID. + bytes peer_pubkey = 3; + + // The full lnd payment request to send. All fields behave the same way as + // they do for lnd's routerrpc.SendPaymentV2 RPC method (see the API docs + // at https://lightning.engineering/api-docs/api/lnd/router/send-payment-v2 + // for more details). + // To send a keysend payment, the payment_request.dest_custom_records must + // contain a valid keysend record (key 5482373484 and a 32-byte preimage + // that corresponds to the payment hash). + routerrpc.SendPaymentRequest payment_request = 4; + + // The rfq id to use for this payment. If the user sets this value then the + // payment will immediately be dispatched, skipping the rfq negotiation + // phase, and using the following rfq id instead. + bytes rfq_id = 5; +} + +message SendPaymentResponse { + oneof result { + // In case channel assets need to be swapped to another asset, an asset + // sell order is negotiated with the channel peer. The result will be + // the first message in the response stream. If no swap is needed, the + // payment results will be streamed directly. + rfqrpc.PeerAcceptedSellQuote accepted_sell_order = 1; + + // The payment result of a single payment attempt. Multiple attempts may + // be returned per payment request until either the payment succeeds or + // the payment times out. + lnrpc.Payment payment_result = 2; + } +} + +message HodlInvoice { + bytes payment_hash = 1; +} + +message AddInvoiceRequest { + // The asset ID to use for the invoice. + bytes asset_id = 1; + + // The asset amount to receive. + uint64 asset_amount = 2; + + // The node identity public key of the peer to ask for a quote for receiving + // assets and converting them from satoshis. This must be specified if + // there are multiple channels with the given asset ID. + bytes peer_pubkey = 3; + + // The full lnd invoice request to send. All fields (except for the value + // and the route hints) behave the same way as they do for lnd's + // lnrpc.AddInvoice RPC method (see the API docs at + // https://lightning.engineering/api-docs/api/lnd/lightning/add-invoice + // for more details). The value/value_msat fields will be overwritten by the + // satoshi (or milli-satoshi) equivalent of the asset amount, after + // negotiating a quote with a peer that supports the given asset ID. + lnrpc.Invoice invoice_request = 4; + + // If set, then this will make the invoice created a hodl invoice, which + // won't be settled automatically. Instead, users will need to use the + // invoicesrpc.SettleInvoice call to manually settle the invoice. + HodlInvoice hodl_invoice = 5; +} + +message AddInvoiceResponse { + // The quote for the purchase of assets that was accepted by the peer. + rfqrpc.PeerAcceptedBuyQuote accepted_buy_quote = 1; + + // The result of the invoice creation. + lnrpc.AddInvoiceResponse invoice_result = 2; +} diff --git a/protos/tapd/v0.5.0-rc2/tapdevrpc/tapdev.proto b/protos/tapd/v0.5.0-rc2/tapdevrpc/tapdev.proto new file mode 100644 index 0000000..b1c0f53 --- /dev/null +++ b/protos/tapd/v0.5.0-rc2/tapdevrpc/tapdev.proto @@ -0,0 +1,116 @@ +syntax = "proto3"; + +import "taprootassets.proto"; + +package tapdevrpc; + +option go_package = "github.com/lightninglabs/taproot-assets/taprpc/tapdevrpc"; + +service TapDev { + /* tapcli: `dev importproof` + ImportProof attempts to import a proof file into the daemon. If successful, + a new asset will be inserted on disk, spendable using the specified target + script key, and internal key. + */ + rpc ImportProof (ImportProofRequest) returns (ImportProofResponse); + + /* + SubscribeSendAssetEventNtfns registers a subscription to the event + notification stream which relates to the asset sending process. + */ + rpc SubscribeSendAssetEventNtfns (SubscribeSendAssetEventNtfnsRequest) + returns (stream SendAssetEvent); + + /* + SubscribeReceiveAssetEventNtfns registers a subscription to the event + notification stream which relates to the asset receive process. + */ + rpc SubscribeReceiveAssetEventNtfns (SubscribeReceiveAssetEventNtfnsRequest) + returns (stream ReceiveAssetEvent); +} + +message ImportProofRequest { + bytes proof_file = 1; + + string genesis_point = 2; +} + +message ImportProofResponse { +} + +message SubscribeSendAssetEventNtfnsRequest { +} + +message SendAssetEvent { + oneof event { + // An event which indicates that a send state is about to be executed. + ExecuteSendStateEvent execute_send_state_event = 1; + + // An event which indicates that the proof transfer backoff wait period + // will start imminently. + ProofTransferBackoffWaitEvent proof_transfer_backoff_wait_event = 2; + } +} + +message ExecuteSendStateEvent { + // Execute timestamp (microseconds). + int64 timestamp = 1; + + // The send state that is about to be executed. + string send_state = 2; +} + +// ProofTransferType is the type of proof transfer attempt. The transfer is +// either a proof delivery to the transfer counterparty or receiving a proof +// from the transfer counterparty. Note that the transfer counterparty is +// usually the proof courier service. +enum ProofTransferType { + // This value indicates that the proof transfer attempt is a delivery to the + // transfer counterparty. + PROOF_TRANSFER_TYPE_SEND = 0; + + // This value indicates that the proof transfer attempt is a receive from + // the transfer counterparty. + PROOF_TRANSFER_TYPE_RECEIVE = 1; +} + +message ProofTransferBackoffWaitEvent { + // Transfer attempt timestamp (microseconds). + int64 timestamp = 1; + + // Backoff is the active backoff wait duration. + int64 backoff = 2; + + // Tries counter is the number of tries we've made so far during the + // course of the current backoff procedure to deliver the proof to the + // receiver. + int64 tries_counter = 3; + + // The type of proof transfer attempt. + ProofTransferType transfer_type = 4; +} + +message SubscribeReceiveAssetEventNtfnsRequest { +} + +message AssetReceiveCompleteEvent { + // Event creation timestamp. + int64 timestamp = 1; + + // The address that received the asset. + taprpc.Addr address = 2; + + // The outpoint of the transaction that was used to receive the asset. + string outpoint = 3; +} + +message ReceiveAssetEvent { + oneof event { + // An event which indicates that the proof transfer backoff wait period + // will start imminently. + ProofTransferBackoffWaitEvent proof_transfer_backoff_wait_event = 1; + + // An event which indicates that an asset receive process has finished. + AssetReceiveCompleteEvent asset_receive_complete_event = 2; + } +} \ No newline at end of file diff --git a/protos/tapd/v0-3-3-lnd-18/taprootassets.proto b/protos/tapd/v0.5.0-rc2/taprootassets.proto similarity index 63% rename from protos/tapd/v0-3-3-lnd-18/taprootassets.proto rename to protos/tapd/v0.5.0-rc2/taprootassets.proto index 18ec031..84d54e7 100644 --- a/protos/tapd/v0-3-3-lnd-18/taprootassets.proto +++ b/protos/tapd/v0.5.0-rc2/taprootassets.proto @@ -104,30 +104,37 @@ service TaprootAssets { */ rpc BurnAsset (BurnAssetRequest) returns (BurnAssetResponse); + /* tapcli: `assets listburns` + ListBurns lists the asset burns that this wallet has performed. These assets + are not recoverable in any way. Filters may be applied to return more + specific results. + */ + rpc ListBurns (ListBurnsRequest) returns (ListBurnsResponse); + /* tapcli: `getinfo` GetInfo returns the information for the node. */ rpc GetInfo (GetInfoRequest) returns (GetInfoResponse); - /* - SubscribeSendAssetEventNtfns registers a subscription to the event - notification stream which relates to the asset sending process. - */ - rpc SubscribeSendAssetEventNtfns (SubscribeSendAssetEventNtfnsRequest) - returns (stream SendAssetEvent); - - /* - SubscribeReceiveAssetEventNtfns registers a subscription to the event - notification stream which relates to the asset receive process. - */ - rpc SubscribeReceiveAssetEventNtfns (SubscribeReceiveAssetEventNtfnsRequest) - returns (stream ReceiveAssetEvent); - /* tapcli: `assets meta` FetchAssetMeta allows a caller to fetch the reveal meta data for an asset either by the asset ID for that asset, or a meta hash. */ rpc FetchAssetMeta (FetchAssetMetaRequest) returns (AssetMeta); + + /* tapcli: `events receive` + SubscribeReceiveEvents allows a caller to subscribe to receive events for + incoming asset transfers. + */ + rpc SubscribeReceiveEvents (SubscribeReceiveEventsRequest) + returns (stream ReceiveEvent); + + /* tapcli: `events send` + SubscribeSendEvents allows a caller to subscribe to send events for outgoing + asset transfers. + */ + rpc SubscribeSendEvents (SubscribeSendEventsRequest) + returns (stream SendEvent); } enum AssetType { @@ -152,6 +159,12 @@ enum AssetMetaType { should be interpreted as opaque blobs. */ META_TYPE_OPAQUE = 0; + + /* + JSON is used for asset meta blobs that are to be interpreted as valid JSON + strings. + */ + META_TYPE_JSON = 1; } message AssetMeta { @@ -176,6 +189,13 @@ message ListAssetRequest { bool with_witness = 1; bool include_spent = 2; bool include_leased = 3; + + // List assets that aren't confirmed yet. Only freshly minted assets will + // show in the asset list with a block height of 0. All other forms of + // unconfirmed assets will not appear in the list until the transaction is + // confirmed (check either transfers or receives for unconfirmed outbound or + // inbound assets). + bool include_unconfirmed_mints = 4; } message AnchorInfo { @@ -233,9 +253,77 @@ message GenesisInfo { the genesis transaction. */ uint32 output_index = 6; +} + +message GroupKeyRequest { + // The internal key for the asset group before any tweaks have been applied. + KeyDescriptor raw_key = 1; + + /* + The genesis of the group anchor asset, which is used to derive the single + tweak for the group key. For a new group key, this will be the genesis of + new_asset. + */ + GenesisInfo anchor_genesis = 2; + + /* + The optional root of a tapscript tree that will be used when constructing a + new asset group key. This enables future issuance authorized with a script + witness. + */ + bytes tapscript_root = 3; - // The version of the Taproot Asset commitment that created this asset. - int32 version = 7; + /* + The serialized asset which we are requesting group membership for. A + successful request will produce a witness that authorizes this asset to be a + member of this asset group. + */ + bytes new_asset = 4; +} + +message TxOut { + // The value of the output being spent. + int64 value = 1; + + // The script of the output being spent. + bytes pk_script = 2; +} + +message GroupVirtualTx { + /* + The virtual transaction that represents the genesis state transition of a + grouped asset. + */ + bytes transaction = 1; + + /* + The transaction output that represents a grouped asset. The tweaked + group key is set as the PkScript of this output. This is used in combination + with Tx to produce an asset group witness. + */ + TxOut prev_out = 2; + + /* + The asset ID of the grouped asset in a GroupKeyRequest. This ID is + needed to construct a sign descriptor, as it is the single tweak for the + group internal key. + */ + bytes genesis_id = 3; + + /* + The tweaked group key for a specific GroupKeyRequest. This is used to + construct a complete group key after producing an asset group witness. + */ + bytes tweaked_key = 4; +} + +message GroupWitness { + // The asset ID of the pending asset that should be assigned this asset + // group witness. + bytes genesis_id = 1; + + // The serialized witness stack for the asset group. + repeated bytes witness = 2; } message AssetGroup { @@ -254,7 +342,11 @@ message AssetGroup { */ bytes asset_witness = 3; - // TODO(jhb): update to include tapscript_root + /* + The root hash of a tapscript tree, which enables future issuance authorized + with a script witness. + */ + bytes tapscript_root = 4; } message GroupKeyReveal { @@ -270,6 +362,22 @@ message GenesisReveal { GenesisInfo genesis_base_reveal = 1; } +message DecimalDisplay { + /* + Decimal display dictates the number of decimal places to shift the amount to + the left converting from Taproot Asset integer representation to a + UX-recognizable fractional quantity. + + For example, if the decimal_display value is 2 and there's 100 of those + assets, then a wallet would display the amount as "1.00". This field is + intended as information for wallets that display balances and has no impact + on the behavior of the daemon or any other part of the protocol. This value + is encoded in the MetaData field as a JSON field, therefore it is only + compatible with assets that have a JSON MetaData field. + */ + uint32 decimal_display = 1; +} + enum AssetVersion { // ASSET_VERSION_V0 is the default asset version. This version will include // the witness vector in the leaf for a tap commitment. @@ -328,6 +436,29 @@ message Asset { // Indicates whether this transfer was an asset burn. If true, the number of // assets in this output are destroyed and can no longer be spent. bool is_burn = 17; + + // Indicates whether this script key has either been derived by the local + // wallet or was explicitly declared to be known by using the + // DeclareScriptKey RPC. Knowing the key conceptually means the key belongs + // to the local wallet or is at least known by a software that operates on + // the local wallet. The flag is never serialized in proofs, so this is + // never explicitly set for keys foreign to the local wallet. Therefore, if + // this method returns true for a script key, it means the asset with the + // script key will be shown in the wallet balance. + bool script_key_declared_known = 18; + + // Indicates whether the script key is known to have a Tapscript spend path, + // meaning that the Taproot merkle root tweak is not empty. This will only + // ever be true if either script_key_is_local or script_key_internals_known + // is true as well, since the presence of a Tapscript spend path cannot be + // determined for script keys that aren't known to the wallet of the local + // tapd node. + bool script_key_has_script_path = 19; + + // This field defines a decimal display value that may be present. If this + // field is null, it means the presence of a decimal display field is + // unknown in the current context. + DecimalDisplay decimal_display = 20; } message PrevWitness { @@ -344,6 +475,15 @@ message SplitCommitment { message ListAssetResponse { repeated Asset assets = 1; + + // This is a count of unconfirmed outgoing transfers. Unconfirmed transfers + // do not appear as assets in this endpoint response. + uint64 unconfirmed_transfers = 2; + + // This is a count of freshly minted assets that haven't been confirmed on + // chain yet. These assets will appear in the asset list with a block height + // of 0 if include_unconfirmed_mints is set to true in the request. + uint64 unconfirmed_mints = 3; } message ListUtxosRequest { @@ -372,6 +512,13 @@ message ManagedUtxo { // The assets held at this UTXO. repeated Asset assets = 6; + + // The lease owner for this UTXO. If blank the UTXO isn't leased. + bytes lease_owner = 7; + + // The expiry time as a unix time stamp for this lease. If blank the utxo + // isn't leased. + int64 lease_expiry_unix = 8; } message ListUtxosResponse { @@ -435,6 +582,9 @@ message ListBalancesRequest { // group key filter may be provided to query the balance of a specific // asset group. bytes group_key_filter = 4; + + // An option to include previous leased assets in the balances. + bool include_leased = 5; } message AssetBalance { @@ -460,6 +610,10 @@ message ListBalancesResponse { } message ListTransfersRequest { + // anchor_txid specifies the hexadecimal encoded txid string of the anchor + // transaction for which to retrieve transfers. An empty value indicates + // that this parameter should be disregarded in transfer selection. + string anchor_txid = 1; } message ListTransfersResponse { @@ -467,6 +621,28 @@ message ListTransfersResponse { repeated AssetTransfer transfers = 1; } +// ChainHash represents a hash value, typically a double SHA-256 of some data. +// Common examples include block hashes and transaction hashes. +// +// This versatile message type is used in various Bitcoin-related messages and +// structures, providing two different formats of the same hash to accommodate +// both developer and user needs. +message ChainHash { + // The raw hash value in byte format. + // + // This format is optimized for programmatic use, particularly for Go + // developers, enabling easy integration with other RPC calls or binary + // operations. + bytes hash = 1; + + // The byte-reversed hash value as a hexadecimal string. + // + // This format is intended for human interaction, making it easy to copy, + // paste, and use in contexts like command-line arguments or configuration + // files. + string hash_str = 2; +} + message AssetTransfer { int64 transfer_timestamp = 1; @@ -483,6 +659,11 @@ message AssetTransfer { // Describes the set of newly created asset outputs. repeated TransferOutput outputs = 6; + + // The block hash of the blockchain block that contains the anchor + // transaction. If this value is unset, the anchor transaction is + // unconfirmed. + ChainHash anchor_tx_block_hash = 7; } message TransferInput { @@ -529,24 +710,26 @@ enum OutputType { // output. In either case, the asset of this output has a tx witness. OUTPUT_TYPE_SPLIT_ROOT = 1; - // OUTPUT_TYPE_PASSIVE_ASSETS_ONLY indicates that this output only carries - // passive assets and therefore the asset in this output is nil. The passive - // assets themselves are signed in their own virtual transactions and - // are not present in this packet. - OUTPUT_TYPE_PASSIVE_ASSETS_ONLY = 2; + reserved 2; - // OUTPUT_TYPE_PASSIVE_SPLIT_ROOT is a split root output that carries the - // change from a split or a tombstone from a non-interactive full value send - // output, as well as passive assets. - OUTPUT_TYPE_PASSIVE_SPLIT_ROOT = 3; + reserved 3; - // OUTPUT_TYPE_SIMPLE_PASSIVE_ASSETS is a plain full-value interactive send - // output that also carries passive assets. This is a special case where we - // send the full value of a single asset in a commitment to a new script - // key, but also carry passive assets in the same output. This is useful for - // key rotation (send-to-self) scenarios or asset burns where we burn the - // full supply of a single asset within a commitment. - OUTPUT_TYPE_SIMPLE_PASSIVE_ASSETS = 4; + reserved 4; +} + +// ProofDeliveryStatus is an enum that describes the status of the delivery of +// a proof associated with an asset transfer output. +enum ProofDeliveryStatus { + // Delivery is not applicable; the proof will not be delivered. + PROOF_DELIVERY_STATUS_NOT_APPLICABLE = 0; + + // The proof has been successfully delivered. + PROOF_DELIVERY_STATUS_COMPLETE = 1; + + // The proof is pending delivery. This status indicates that the proof has + // not yet been delivered successfully. One or more attempts at proof + // delivery may have been made. + PROOF_DELIVERY_STATUS_PENDING = 2; } message TransferOutput { @@ -567,6 +750,13 @@ message TransferOutput { OutputType output_type = 7; AssetVersion asset_version = 8; + + uint64 lock_time = 9; + + uint64 relative_lock_time = 10; + + // The delivery status of the proof associated with this output. + ProofDeliveryStatus proof_delivery_status = 11; } message StopRequest { @@ -585,6 +775,19 @@ message DebugLevelResponse { string sub_systems = 1; } +enum AddrVersion { + // ADDR_VERSION_UNSPECIFIED is the default value for an address version in + // an RPC message. It is unmarshalled to the latest address version. + ADDR_VERSION_UNSPECIFIED = 0; + + // ADDR_VERSION_V0 is the initial address version. + ADDR_VERSION_V0 = 1; + + // ADDR_VERSION_V1 is the address version that uses V2 Taproot Asset + // commitments. + ADDR_VERSION_V1 = 2; +} + message Addr { // The bech32 encoded Taproot Asset address. string encoded = 1; @@ -630,6 +833,9 @@ message Addr { // The asset version of the address. AssetVersion asset_version = 11; + + // The version of the address. + AddrVersion address_version = 12; } message QueryAddrRequest { @@ -699,6 +905,11 @@ message NewAddrRequest { The asset version to use when sending/receiving to/from this address. */ AssetVersion asset_version = 7; + + /* + The version of this address. + */ + AddrVersion address_version = 8; } message ScriptKey { @@ -745,6 +956,26 @@ message KeyDescriptor { KeyLocator key_loc = 2; } +message TapscriptFullTree { + /* + The complete, ordered list of all tap leaves of the tree. + */ + repeated TapLeaf all_leaves = 1; +} + +message TapLeaf { + // The script of the tap leaf. + bytes script = 2; +} + +message TapBranch { + // The TapHash of the left child of the root hash of a Tapscript tree. + bytes left_taphash = 1; + + // The TapHash of the right child of the root hash of a Tapscript tree. + bytes right_taphash = 2; +} + message DecodeAddrRequest { string addr = 1; } @@ -947,83 +1178,6 @@ message GetInfoResponse { bool sync_to_chain = 8; } -message SubscribeSendAssetEventNtfnsRequest { -} - -message SendAssetEvent { - oneof event { - // An event which indicates that a send state is about to be executed. - ExecuteSendStateEvent execute_send_state_event = 1; - - // An event which indicates that the proof transfer backoff wait period - // will start imminently. - ProofTransferBackoffWaitEvent proof_transfer_backoff_wait_event = 2; - } -} - -message ExecuteSendStateEvent { - // Execute timestamp (microseconds). - int64 timestamp = 1; - - // The send state that is about to be executed. - string send_state = 2; -} - -// ProofTransferType is the type of proof transfer attempt. The transfer is -// either a proof delivery to the transfer counterparty or receiving a proof -// from the transfer counterparty. Note that the transfer counterparty is -// usually the proof courier service. -enum ProofTransferType { - // This value indicates that the proof transfer attempt is a delivery to the - // transfer counterparty. - PROOF_TRANSFER_TYPE_SEND = 0; - - // This value indicates that the proof transfer attempt is a receive from - // the transfer counterparty. - PROOF_TRANSFER_TYPE_RECEIVE = 1; -} - -message ProofTransferBackoffWaitEvent { - // Transfer attempt timestamp (microseconds). - int64 timestamp = 1; - - // Backoff is the active backoff wait duration. - int64 backoff = 2; - - // Tries counter is the number of tries we've made so far during the - // course of the current backoff procedure to deliver the proof to the - // receiver. - int64 tries_counter = 3; - - // The type of proof transfer attempt. - ProofTransferType transfer_type = 4; -} - -message SubscribeReceiveAssetEventNtfnsRequest { -} - -message AssetReceiveCompleteEvent { - // Event creation timestamp. - int64 timestamp = 1; - - // The address that received the asset. - Addr address = 2; - - // The outpoint of the transaction that was used to receive the asset. - string outpoint = 3; -} - -message ReceiveAssetEvent { - oneof event { - // An event which indicates that the proof transfer backoff wait period - // will start imminently. - ProofTransferBackoffWaitEvent proof_transfer_backoff_wait_event = 1; - - // An event which indicates that an asset receive process has finished. - AssetReceiveCompleteEvent asset_receive_complete_event = 2; - } -} - message FetchAssetMetaRequest { oneof asset { // The asset ID of the asset to fetch the meta for. @@ -1055,6 +1209,9 @@ message BurnAssetRequest { // the burn. This needs to be set to the value "assets will be destroyed" // for the burn to succeed. string confirmation_text = 4; + + // A note that may contain user defined metadata related to this burn. + string note = 5; } message BurnAssetResponse { @@ -1065,6 +1222,38 @@ message BurnAssetResponse { DecodedProof burn_proof = 2; } +message ListBurnsRequest { + // The asset id of the burnt asset. + bytes asset_id = 1; + + // The tweaked group key of the group this asset belongs to. + bytes tweaked_group_key = 3; + + // The txid of the transaction that the burn was anchored to. + bytes anchor_txid = 4; +} + +message AssetBurn { + // A note that may contain user defined metadata related to this burn. + string note = 1; + + // The asset id of the burnt asset. + bytes asset_id = 2; + + // The tweaked group key of the group this asset belongs to. + bytes tweaked_group_key = 3; + + // The amount of burnt assets. + uint64 amount = 4; + + // The txid of the transaction that the burn was anchored to. + bytes anchor_txid = 5; +} + +message ListBurnsResponse { + repeated AssetBurn burns = 1; +} + message OutPoint { /* Raw bytes representing the transaction id. @@ -1076,3 +1265,168 @@ message OutPoint { */ uint32 output_index = 2; } + +message SubscribeReceiveEventsRequest { + // Filter receives by a specific address. Leave empty to get all receive + // events for all addresses. + string filter_addr = 1; + + // The start time as a Unix timestamp in microseconds. If not set (default + // value 0), the daemon will start streaming events from the current time. + int64 start_timestamp = 2; +} + +message ReceiveEvent { + // Event creation timestamp (Unix timestamp in microseconds). + int64 timestamp = 1; + + // The address that received the asset. + taprpc.Addr address = 2; + + // The outpoint of the transaction that was used to receive the asset. + string outpoint = 3; + + // The status of the event. If error below is set, then the status is the + // state that lead to the error during its execution. + AddrEventStatus status = 4; + + // The height of the block the asset receive transaction was mined in. This + // is only set if the status is ADDR_EVENT_STATUS_TRANSACTION_CONFIRMED or + // later. + uint32 confirmation_height = 5; + + // An optional error, indicating that executing the status above failed. + string error = 6; +} + +message SubscribeSendEventsRequest { + // Filter send events by a specific recipient script key. Leave empty to get + // all receive events for all parcels. + bytes filter_script_key = 1; +} + +enum SendState { + // Input coin selection to pick out which asset inputs should be spent is + // executed during this state. + SEND_STATE_VIRTUAL_INPUT_SELECT = 0; + + // The virtual transaction is signed during this state. + SEND_STATE_VIRTUAL_SIGN = 1; + + // The Bitcoin anchor transaction is signed during this state. + SEND_STATE_ANCHOR_SIGN = 2; + + // The outbound packet is written to the database during this state, + // including the partial proof suffixes. Only parcels that complete this + // state can be resumed on restart. + SEND_STATE_LOG_COMMITMENT = 3; + + // The Bitcoin anchor transaction is broadcast to the network during this + // state. + SEND_STATE_BROADCAST = 4; + + // The on-chain anchor transaction needs to reach at least 1 confirmation. + // This state waits for the confirmation. + SEND_STATE_WAIT_CONFIRMATION = 5; + + // The anchor transaction was confirmed in a block and the full proofs can + // now be constructed during this stage. + SEND_STATE_STORE_PROOFS = 6; + + // The full proofs are sent to the recipient(s) with the proof courier + // service during this state. + SEND_STATE_TRANSFER_PROOFS = 7; + + // The send state machine has completed the send process. + SEND_STATE_COMPLETED = 8; +} + +enum ParcelType { + // The parcel is an address parcel. + PARCEL_TYPE_ADDRESS = 0; + + // The parcel type is a pre-signed parcel where the virtual transactions are + // signed outside of the send state machine. Parcels of this type will only + // get send states starting from SEND_STATE_ANCHOR_SIGN. + PARCEL_TYPE_PRE_SIGNED = 1; + + // The parcel is pending and was resumed on the latest restart of the + // daemon. The original parcel type (address or pre-signed) is not known + // anymore, as it's not relevant for the remaining steps. Parcels of this + // type will only get send states starting from SEND_STATE_BROADCAST. + PARCEL_TYPE_PENDING = 2; + + // The parcel type is a pre-anchored parcel where the full anchor + // transaction and all proofs are already available. Parcels of this type + // will only get send states starting from SEND_STATE_LOG_COMMITMENT. + PARCEL_TYPE_PRE_ANCHORED = 3; +} + +message SendEvent { + // Execute timestamp (Unix timestamp in microseconds). + int64 timestamp = 1; + + // The send state that was executed successfully. If error below is set, + // then the send_state is the state that lead to the error during its + // execution. + string send_state = 2; + + // The type of the outbound send parcel. + ParcelType parcel_type = 3; + + // The list of addresses the parcel sends to (recipient addresses only, not + // including change going back to own wallet). This is only set for parcels + // of type PARCEL_TYPE_ADDRESS. + repeated taprpc.Addr addresses = 4; + + // The virtual packets that are part of the parcel. + repeated bytes virtual_packets = 5; + + // The passive virtual packets that are carried along with the parcel. This + // is empty if there were no other assets in the input commitment that is + // being spent with the "active" virtual packets above. + repeated bytes passive_virtual_packets = 6; + + // The Bitcoin on-chain anchor transaction that commits the sent assets + // on-chain. This is only set after the send state SEND_STATE_ANCHOR_SIGN. + AnchorTransaction anchor_transaction = 7; + + // The final transfer as it will be stored in the database. This is only set + // after the send state SEND_STATE_LOG_COMMITMENT. + AssetTransfer transfer = 8; + + // An optional error, indicating that executing the send_state failed. + string error = 9; +} + +message AnchorTransaction { + bytes anchor_psbt = 1; + + /* + The index of the (added) change output or -1 if no change was left over. + */ + int32 change_output_index = 2; + + /* + The total number of satoshis in on-chain fees paid by the anchor + transaction. + */ + int64 chain_fees_sats = 3; + + /* + The fee rate in sat/kWU that was targeted by the anchor transaction. + */ + int32 target_fee_rate_sat_kw = 4; + + /* + The list of UTXO lock leases that were acquired for the inputs in the funded + PSBT packet from lnd. Only inputs added to the PSBT by this RPC are locked, + inputs that were already present in the PSBT are not locked. + */ + repeated taprpc.OutPoint lnd_locked_utxos = 5; + + /* + The final, signed anchor transaction that was broadcast to the network. + */ + bytes final_tx = 6; +} diff --git a/protos/tapd/v0-3-3-lnd-18/universerpc/universe.proto b/protos/tapd/v0.5.0-rc2/universerpc/universe.proto similarity index 91% rename from protos/tapd/v0-3-3-lnd-18/universerpc/universe.proto rename to protos/tapd/v0.5.0-rc2/universerpc/universe.proto index 20db158..f719fb9 100644 --- a/protos/tapd/v0-3-3-lnd-18/universerpc/universe.proto +++ b/protos/tapd/v0.5.0-rc2/universerpc/universe.proto @@ -7,6 +7,13 @@ package universerpc; option go_package = "github.com/lightninglabs/taproot-assets/taprpc/universerpc"; service Universe { + /* tapcli: `universe multiverse` + MultiverseRoot returns the root of the multiverse tree. This is useful to + determine the equality of two multiverse trees, since the root can directly + be compared to another multiverse root to find out if a sync is required. + */ + rpc MultiverseRoot (MultiverseRootRequest) returns (MultiverseRootResponse); + /* tapcli: `universe roots` AssetRoots queries for the known Universe roots associated with each known asset. These roots represent the supply/audit state for each known asset. @@ -65,6 +72,13 @@ service Universe { */ rpc InsertProof (AssetProof) returns (AssetProofResponse); + /* tapcli: `universe proofs push` + PushProof attempts to query the local universe for a proof specified by a + UniverseKey. If found, a connection is made to a remote Universe server to + attempt to upload the asset leaf. + */ + rpc PushProof (PushProofRequest) returns (PushProofResponse); + // TODO(roasbeef): rename resp to UniverseStateUpdate? ^ /* tapcli: `universe info` @@ -142,6 +156,22 @@ service Universe { returns (QueryFederationSyncConfigResponse); } +message MultiverseRootRequest { + // The proof type to calculate the multiverse root for. + ProofType proof_type = 1; + + // An optional list of universe IDs to include in the multiverse root. If + // none are specified, then all known universes of the given proof type are + // included. NOTE: The proof type within the IDs must either be unspecified + // or match the proof type above. + repeated ID specific_ids = 2; +} + +message MultiverseRootResponse { + // The root of the multiverse tree. + MerkleSumNode multiverse_root = 1; +} + message AssetRootRequest { // If true, then the response will include the amounts for each asset ID // of grouped assets. @@ -317,7 +347,7 @@ message UniverseKey { } message AssetProofResponse { - // The request original request for the issuance proof. + // The original request for the issuance proof. UniverseKey req = 1; // The Universe root that includes this asset leaf. @@ -347,6 +377,19 @@ message AssetProof { AssetLeaf asset_leaf = 4; } +message PushProofRequest { + // The ID of the asset to push the proof for. + UniverseKey key = 1; + + // The universe server to push the proof to. + UniverseFederationServer server = 2; +} + +message PushProofResponse { + // The ID of the asset a push was requested for. + UniverseKey key = 1; +} + message InfoRequest { } diff --git a/scripts/generate_types.sh b/scripts/generate_types.sh index bce1f4e..a058726 100644 --- a/scripts/generate_types.sh +++ b/scripts/generate_types.sh @@ -45,7 +45,7 @@ else fi curl -L ${PROTOC_URL} -o "protoc-${PROTOC_VERSION}.zip" -unzip "protoc-${PROTOC_VERSION}.zip" -d protoc +unzip -o "protoc-${PROTOC_VERSION}.zip" -d protoc rm "protoc-${PROTOC_VERSION}.zip" TS_PROTO_OPTIONS="\ @@ -112,12 +112,17 @@ echo "TAPD: running protoc..." mkdir -p "$GENERATED_TYPES_DIR/tapd" protoc/bin/protoc \ --proto_path=protos/tapd/${TAPD_RELEASE_TAG} \ + --proto_path=protos/lnd/${LND_RELEASE_TAG} \ --plugin=./node_modules/.bin/protoc-gen-ts_proto \ --ts_proto_out=$GENERATED_TYPES_DIR/tapd \ $TS_PROTO_OPTIONS \ taprootassets.proto \ assetwalletrpc/assetwallet.proto \ mintrpc/mint.proto \ + priceoraclerpc/price_oracle.proto \ + rfqrpc/rfq.proto \ + tapchannelrpc/tapchannel.proto \ + tapdevrpc/tapdev.proto \ universerpc/universe.proto echo "LiT: running protoc..." @@ -201,12 +206,17 @@ echo "TAPD: generating schema..." mkdir -p "$SCHEMA_DIR/tapd" protoc/bin/protoc \ --proto_path=protos/tapd/${TAPD_RELEASE_TAG} \ + --proto_path=protos/lnd/${LND_RELEASE_TAG} \ --plugin=./node_modules/.bin/protoc-gen-ts_proto \ --ts_proto_out=$SCHEMA_DIR/tapd \ $SCHEMA_PROTO_OPTIONS \ taprootassets.proto \ assetwalletrpc/assetwallet.proto \ mintrpc/mint.proto \ + priceoraclerpc/price_oracle.proto \ + rfqrpc/rfq.proto \ + tapchannelrpc/tapchannel.proto \ + tapdevrpc/tapdev.proto \ universerpc/universe.proto echo "LIT: generating schema..." diff --git a/scripts/process_types.ts b/scripts/process_types.ts index b7d7076..8a427cc 100644 --- a/scripts/process_types.ts +++ b/scripts/process_types.ts @@ -129,9 +129,16 @@ schemaFiles.forEach((file) => { if (!services[pkgName]) services[pkgName] = {}; services[pkgName][serviceDef.name] = serviceDef.fullName; - // add the package file to the pkgFiles object + // add the package file to the pkgFiles object if it doesn't exist already. + // ex: lightning.proto is imported by both lnd and tapd. We only want to include + // it once in the lightning.ts file if (!pkgFiles[pkgName]) pkgFiles[pkgName] = []; - pkgFiles[pkgName].push(file.replace(schemaDir, '')); + const existing = pkgFiles[pkgName].find( + (f) => path.basename(f) === path.basename(file) + ); + if (!existing) { + pkgFiles[pkgName].push(file.replace(schemaDir, '')); + } // extract subscription methods into the array Object.values(serviceDef.methods).forEach((m: any) => { diff --git a/scripts/update_protos.sh b/scripts/update_protos.sh index dc515bb..5b3572f 100644 --- a/scripts/update_protos.sh +++ b/scripts/update_protos.sh @@ -49,6 +49,10 @@ curl ${FARADAY_URL}/${FARADAY_RELEASE_TAG}/frdrpc/faraday.proto --create-dirs -o curl ${TAPD_URL}/${TAPD_RELEASE_TAG}/taprpc/taprootassets.proto --create-dirs -o protos/tapd/${TAPD_RELEASE_TAG}/taprootassets.proto curl ${TAPD_URL}/${TAPD_RELEASE_TAG}/taprpc/assetwalletrpc/assetwallet.proto --create-dirs -o protos/tapd/${TAPD_RELEASE_TAG}/assetwalletrpc/assetwallet.proto curl ${TAPD_URL}/${TAPD_RELEASE_TAG}/taprpc/mintrpc/mint.proto --create-dirs -o protos/tapd/${TAPD_RELEASE_TAG}/mintrpc/mint.proto +curl ${TAPD_URL}/${TAPD_RELEASE_TAG}/taprpc/priceoraclerpc/price_oracle.proto --create-dirs -o protos/tapd/${TAPD_RELEASE_TAG}/priceoraclerpc/price_oracle.proto +curl ${TAPD_URL}/${TAPD_RELEASE_TAG}/taprpc/rfqrpc/rfq.proto --create-dirs -o protos/tapd/${TAPD_RELEASE_TAG}/rfqrpc/rfq.proto +curl ${TAPD_URL}/${TAPD_RELEASE_TAG}/taprpc/tapchannelrpc/tapchannel.proto --create-dirs -o protos/tapd/${TAPD_RELEASE_TAG}/tapchannelrpc/tapchannel.proto +curl ${TAPD_URL}/${TAPD_RELEASE_TAG}/taprpc/tapdevrpc/tapdev.proto --create-dirs -o protos/tapd/${TAPD_RELEASE_TAG}/tapdevrpc/tapdev.proto curl ${TAPD_URL}/${TAPD_RELEASE_TAG}/taprpc/universerpc/universe.proto --create-dirs -o protos/tapd/${TAPD_RELEASE_TAG}/universerpc/universe.proto curl ${LIT_URL}/${LIT_RELEASE_TAG}/litrpc/firewall.proto --create-dirs -o protos/lit/${LIT_RELEASE_TAG}/firewall.proto