diff --git a/lib/types/proto/authmailboxrpc.ts b/lib/types/proto/authmailboxrpc.ts new file mode 100644 index 0000000..c0d3625 --- /dev/null +++ b/lib/types/proto/authmailboxrpc.ts @@ -0,0 +1 @@ +export * from './tapd/authmailboxrpc/mailbox'; diff --git a/lib/types/proto/index.ts b/lib/types/proto/index.ts index 5a5463c..1dad639 100644 --- a/lib/types/proto/index.ts +++ b/lib/types/proto/index.ts @@ -4,6 +4,7 @@ import * as autopilotrpc from './autopilotrpc'; import * as chainrpc from './chainrpc'; import * as invoicesrpc from './invoicesrpc'; import * as lnrpc from './lnrpc'; +import * as peersrpc from './peersrpc'; import * as routerrpc from './routerrpc'; import * as signrpc from './signrpc'; import * as walletrpc from './walletrpc'; @@ -12,6 +13,7 @@ import * as wtclientrpc from './wtclientrpc'; import * as looprpc from './looprpc'; import * as poolrpc from './poolrpc'; import * as assetwalletrpc from './assetwalletrpc'; +import * as authmailboxrpc from './authmailboxrpc'; import * as mintrpc from './mintrpc'; import * as priceoraclerpc from './priceoraclerpc'; import * as rfqrpc from './rfqrpc'; @@ -26,6 +28,7 @@ export { chainrpc, invoicesrpc, lnrpc, + peersrpc, routerrpc, signrpc, walletrpc, @@ -34,6 +37,7 @@ export { looprpc, poolrpc, assetwalletrpc, + authmailboxrpc, mintrpc, priceoraclerpc, rfqrpc, diff --git a/lib/types/proto/lnd/lightning.ts b/lib/types/proto/lnd/lightning.ts index e89b73c..fbdf460 100644 --- a/lib/types/proto/lnd/lightning.ts +++ b/lib/types/proto/lnd/lightning.ts @@ -1236,6 +1236,7 @@ export interface Peer { */ errors: TimestampedError[]; /** + * This field is populated when the peer has at least one channel with us. * 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 @@ -1243,6 +1244,7 @@ export interface Peer { */ flapCount: number; /** + * This field is populated when the peer has at least one channel with us. * 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. */ @@ -1400,12 +1402,6 @@ export interface Chain { network: string; } -export interface ConfirmationUpdate { - blockSha: Uint8Array | string; - blockHeight: number; - numConfsLeft: number; -} - export interface ChannelOpenUpdate { channelPoint: ChannelPoint | undefined; } @@ -2123,6 +2119,27 @@ export interface PendingChannelsResponse_PendingOpenChannel { * fully operational. */ fundingExpiryBlocks: number; + /** + * The number of blocks remaining until the channel status changes from + * pending to active. A value of 0 indicates that the channel is now + * active. + * + * "Active" here means both channel peers have the channel marked OPEN + * and can immediately start using it. For public channels, this does + * not imply a channel_announcement has been gossiped. It only becomes + * public on the network after 6 on‐chain confirmations. + * See BOLT07 "Routing Gossip": + * https://github.com/lightning/bolts/blob/master/07-routing-gossip.md + * + * ZeroConf channels bypass the pending state entirely: they are marked + * active immediately upon creation, so they never show up as "pending". + */ + confirmationsUntilActive: number; + /** + * The confirmation height records the block height at which the funding + * transaction was first confirmed. + */ + confirmationHeight: number; } export interface PendingChannelsResponse_WaitingCloseChannel { @@ -2220,6 +2237,7 @@ export interface ChannelEventUpdate { inactiveChannel: ChannelPoint | undefined; pendingOpenChannel: PendingUpdate | undefined; fullyResolvedChannel: ChannelPoint | undefined; + channelFundingTimeout: ChannelPoint | undefined; type: ChannelEventUpdate_UpdateType; } @@ -2230,6 +2248,7 @@ export enum ChannelEventUpdate_UpdateType { INACTIVE_CHANNEL = 'INACTIVE_CHANNEL', PENDING_OPEN_CHANNEL = 'PENDING_OPEN_CHANNEL', FULLY_RESOLVED_CHANNEL = 'FULLY_RESOLVED_CHANNEL', + CHANNEL_FUNDING_TIMEOUT = 'CHANNEL_FUNDING_TIMEOUT', UNRECOGNIZED = 'UNRECOGNIZED' } @@ -2391,8 +2410,10 @@ export interface QueryRoutesRequest { */ 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. + * 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. + * + * @deprecated */ outgoingChanId: string; /** The pubkey of the last hop of the route. If empty, any hop may be used. */ @@ -2420,6 +2441,11 @@ export interface QueryRoutesRequest { * only, to 1 to optimize for reliability only or a value inbetween for a mix. */ timePref: number; + /** + * The channel ids of the channels allowed for the first hop. If empty, any + * channel may be used. + */ + outgoingChanIds: string[]; } export interface QueryRoutesRequest_DestCustomRecordsEntry { @@ -2628,6 +2654,11 @@ export interface NodeInfoRequest { pubKey: string; /** If true, will include all known channels associated with the node. */ includeChannels: boolean; + /** + * If true, will include announcements' signatures into ChannelEdge. + * Depends on include_channels. + */ + includeAuthProof: boolean; } export interface NodeInfo { @@ -2686,7 +2717,10 @@ export interface RoutingPolicy { disabled: boolean; maxHtlcMsat: string; lastUpdate: number; - /** Custom channel update tlv records. */ + /** + * Custom channel update tlv records. These are customized fields that are + * not defined by LND and cannot be extracted. + */ customRecords: { [key: string]: Uint8Array | string }; inboundFeeBaseMsat: number; inboundFeeRateMilliMsat: number; @@ -2697,6 +2731,36 @@ export interface RoutingPolicy_CustomRecordsEntry { value: Uint8Array | string; } +/** + * ChannelAuthProof is the authentication proof (the signature portion) for a + * channel. Using the four signatures contained in the struct, and some + * auxiliary knowledge (the funding script, node identities, and outpoint) nodes + * on the network are able to validate the authenticity and existence of a + * channel. + */ +export interface ChannelAuthProof { + /** + * node_sig1 are the raw bytes of the first node signature encoded + * in DER format. + */ + nodeSig1: Uint8Array | string; + /** + * bitcoin_sig1 are the raw bytes of the first bitcoin signature of the + * MultiSigKey key of the channel encoded in DER format. + */ + bitcoinSig1: Uint8Array | string; + /** + * node_sig2 are the raw bytes of the second node signature encoded + * in DER format. + */ + nodeSig2: Uint8Array | string; + /** + * bitcoin_sig2 are the raw bytes of the second bitcoin signature of the + * MultiSigKey key of the channel encoded in DER format. + */ + bitcoinSig2: Uint8Array | string; +} + /** * A fully authenticated channel along with all its unique attributes. * Once an authenticated channel announcement has been processed on the network, @@ -2721,6 +2785,14 @@ export interface ChannelEdge { node2Policy: RoutingPolicy | undefined; /** Custom channel announcement tlv records. */ customRecords: { [key: string]: Uint8Array | string }; + /** + * Authentication proof for this channel. This proof contains a set of + * signatures binding four identities, which attests to the legitimacy of + * the advertised channel. This only is available for advertised channels. + * This field is not filled by default. Pass include_auth_proof flag to + * DescribeGraph, GetNodeInfo or GetChanInfo to get this data. + */ + authProof: ChannelAuthProof | undefined; } export interface ChannelEdge_CustomRecordsEntry { @@ -2735,6 +2807,8 @@ export interface ChannelGraphRequest { * channels, and public channels that are not yet announced to the network. */ includeUnannounced: boolean; + /** If true, will include announcements' signatures into ChannelEdge. */ + includeAuthProof: boolean; } /** Returns a new instance of the directed channel graph. */ @@ -2785,6 +2859,8 @@ export interface ChanInfoRequest { * chan_id is specified, this field is ignored. */ chanPoint: string; + /** If true, will include announcements' signatures into ChannelEdge. */ + includeAuthProof: boolean; } export interface NetworkInfoRequest {} @@ -3181,6 +3257,11 @@ export interface BlindedPathConfig { * blinded paths. */ nodeOmissionList: Uint8Array | string[]; + /** + * The chained channels list specified via channel id (separated by commas), + * starting from a channel owned by the receiver node. + */ + incomingChannelList: string[]; } /** Details of an HTLC that paid to an invoice */ @@ -3345,6 +3426,16 @@ export interface InvoiceSubscription { settleIndex: string; } +export interface DelCanceledInvoiceReq { + /** Invoice payment hash to delete. */ + invoiceHash: string; +} + +export interface DelCanceledInvoiceResp { + /** The status of the delete operation. */ + status: string; +} + export interface Payment { /** The payment hash */ paymentHash: string; @@ -3749,6 +3840,16 @@ export interface ForwardingHistoryRequest { * forwarding event. */ peerAliasLookup: boolean; + /** + * List of incoming channel ids to filter htlcs received from a + * particular channel + */ + incomingChanIds: string[]; + /** + * List of outgoing channel ids to filter htlcs being forwarded to a + * particular channel + */ + outgoingChanIds: string[]; } export interface ForwardingEvent { @@ -3799,6 +3900,16 @@ export interface ForwardingEvent { peerAliasIn: string; /** The peer alias of the outgoing channel. */ peerAliasOut: string; + /** + * The ID of the incoming HTLC in the payment circuit. This field is + * optional and is unset for forwarding events happened before v0.20. + */ + incomingHtlcId?: string | undefined; + /** + * The ID of the outgoing HTLC in the payment circuit. This field is + * optional and may be unset for legacy forwarding events. + */ + outgoingHtlcId?: string | undefined; } export interface ForwardingHistoryResponse { @@ -4087,9 +4198,42 @@ export interface Op { } export interface CheckMacPermRequest { + /** + * The macaroon to check permissions for, serialized in binary format. For + * a macaroon to be valid, it must have been issued by lnd, must succeed all + * caveat conditions, and must contain all of the permissions specified in + * the permissions field. + */ macaroon: Uint8Array | string; + /** + * The list of permissions the macaroon should be checked against. Only if + * the macaroon contains all of these permissions, it is considered valid. + * If the list of permissions given is empty, then the macaroon is + * considered valid only based on issuance authority and caveat validity. + * An empty list of permissions is therefore equivalent to saying "skip + * checking permissions" (unless check_default_perms_from_full_method is + * specified). + */ permissions: MacaroonPermission[]; + /** + * The RPC method to check the macaroon against. This is only used if there + * are custom `uri:./` permissions in + * the permission list above. To check a macaroon against the list of + * permissions of a certain RPC method, query the `ListPermissions` RPC + * first, extract the permissions for the method, and then pass them in the + * `permissions` field above. + */ fullMethod: string; + /** + * If this field is set to true, then the permissions list above MUST be + * empty. The default permissions for the provided fullMethod will be used + * to check the macaroon. This is equivalent to looking up the permissions + * for a method in the `ListPermissions` RPC and then calling this RPC with + * the permission list returned from that call. Without this flag, the list + * of permissions must be non-empty for the check to actually perform a + * permission check. + */ + checkDefaultPermsFromFullMethod: boolean; } export interface CheckMacPermResponse { @@ -4675,6 +4819,14 @@ export interface Lightning { onMessage?: (msg: Invoice) => void, onError?: (err: Error) => void ): void; + /** + * lncli: `deletecanceledinvoice` + * DeleteCanceledInvoice removes a canceled invoice from the database. If the + * invoice is not in the canceled state, an error will be returned. + */ + deleteCanceledInvoice( + request?: DeepPartial + ): Promise; /** * lncli: `decodepayreq` * DecodePayReq takes an encoded payment request string and attempts to decode @@ -4913,9 +5065,10 @@ export interface Lightning { 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 checks whether the provided macaroon contains all + * the provided permissions. If the macaroon is valid (e.g. all caveats are + * satisfied), and all permissions provided in the request are met, then + * this RPC returns true. */ checkMacaroonPermissions( request?: DeepPartial diff --git a/lib/types/proto/lnd/peersrpc/peers.ts b/lib/types/proto/lnd/peersrpc/peers.ts new file mode 100644 index 0000000..9560ed7 --- /dev/null +++ b/lib/types/proto/lnd/peersrpc/peers.ts @@ -0,0 +1,104 @@ +/* eslint-disable */ +import type { FeatureBit, Op } from '../lightning'; + +/** UpdateAction is used to determine the kind of action we are referring to. */ +export enum UpdateAction { + /** ADD - ADD indicates this is an "insertion" kind of action. */ + ADD = 'ADD', + /** REMOVE - REMOVE indicates this is a "deletion" kind of action. */ + REMOVE = 'REMOVE', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export enum FeatureSet { + /** + * SET_INIT - SET_INIT identifies features that should be sent in an Init message to + * a remote peer. + */ + SET_INIT = 'SET_INIT', + /** + * SET_LEGACY_GLOBAL - SET_LEGACY_GLOBAL identifies features that should be set in the legacy + * GlobalFeatures field of an Init message, which maintains backwards + * compatibility with nodes that haven't implemented flat features. + */ + SET_LEGACY_GLOBAL = 'SET_LEGACY_GLOBAL', + /** + * SET_NODE_ANN - SET_NODE_ANN identifies features that should be advertised on node + * announcements. + */ + SET_NODE_ANN = 'SET_NODE_ANN', + /** + * SET_INVOICE - SET_INVOICE identifies features that should be advertised on invoices + * generated by the daemon. + */ + SET_INVOICE = 'SET_INVOICE', + /** + * SET_INVOICE_AMP - SET_INVOICE_AMP identifies the features that should be advertised on + * AMP invoices generated by the daemon. + */ + SET_INVOICE_AMP = 'SET_INVOICE_AMP', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export interface UpdateAddressAction { + /** Determines the kind of action. */ + action: UpdateAction; + /** The address used to apply the update action. */ + address: string; +} + +export interface UpdateFeatureAction { + /** Determines the kind of action. */ + action: UpdateAction; + /** The feature bit used to apply the update action. */ + featureBit: FeatureBit; +} + +export interface NodeAnnouncementUpdateRequest { + /** Set of changes for the features that the node supports. */ + featureUpdates: UpdateFeatureAction[]; + /** Color is the node's color in hex code format. */ + color: string; + /** Alias or nick name of the node. */ + alias: string; + /** Set of changes for the node's known addresses. */ + addressUpdates: UpdateAddressAction[]; +} + +export interface NodeAnnouncementUpdateResponse { + ops: Op[]; +} + +/** + * Peers is a service that can be used to get information and interact + * with the other nodes of the network. + */ +export interface Peers { + /** + * lncli: peers updatenodeannouncement + * UpdateNodeAnnouncement allows the caller to update the node parameters + * and broadcasts a new version of the node announcement to its peers. + */ + updateNodeAnnouncement( + 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/lnd/routerrpc/router.ts b/lib/types/proto/lnd/routerrpc/router.ts index 66add01..14e211f 100644 --- a/lib/types/proto/lnd/routerrpc/router.ts +++ b/lib/types/proto/lnd/routerrpc/router.ts @@ -846,6 +846,16 @@ export interface DeleteAliasesResponse { aliasMaps: AliasMap[]; } +export interface FindBaseAliasRequest { + /** The alias we want to look up the base scid for. */ + alias: string; +} + +export interface FindBaseAliasResponse { + /** The base scid that resulted from the base scid look up. */ + base: string; +} + /** * Router is a service that offers advanced interaction with the router * subsystem of the daemon. @@ -1053,6 +1063,13 @@ export interface Router { xDeleteLocalChanAliases( request?: DeepPartial ): Promise; + /** + * XFindBaseLocalChanAlias is an experimental API that looks up the base scid + * for a local chan alias that was registered during the current runtime. + */ + xFindBaseLocalChanAlias( + request?: DeepPartial + ): Promise; } type Builtin = diff --git a/lib/types/proto/lnd/stateservice.ts b/lib/types/proto/lnd/stateservice.ts new file mode 100644 index 0000000..09aa276 --- /dev/null +++ b/lib/types/proto/lnd/stateservice.ts @@ -0,0 +1,78 @@ +/* eslint-disable */ + +export enum WalletState { + /** NON_EXISTING - NON_EXISTING means that the wallet has not yet been initialized. */ + NON_EXISTING = 'NON_EXISTING', + /** LOCKED - LOCKED means that the wallet is locked and requires a password to unlock. */ + LOCKED = 'LOCKED', + /** + * UNLOCKED - UNLOCKED means that the wallet was unlocked successfully, but RPC server + * isn't ready. + */ + UNLOCKED = 'UNLOCKED', + /** + * RPC_ACTIVE - RPC_ACTIVE means that the lnd server is active but not fully ready for + * calls. + */ + RPC_ACTIVE = 'RPC_ACTIVE', + /** SERVER_ACTIVE - SERVER_ACTIVE means that the lnd server is ready to accept calls. */ + SERVER_ACTIVE = 'SERVER_ACTIVE', + /** + * WAITING_TO_START - WAITING_TO_START means that node is waiting to become the leader in a + * cluster and is not started yet. + */ + WAITING_TO_START = 'WAITING_TO_START', + UNRECOGNIZED = 'UNRECOGNIZED' +} + +export interface SubscribeStateRequest {} + +export interface SubscribeStateResponse { + state: WalletState; +} + +export interface GetStateRequest {} + +export interface GetStateResponse { + state: WalletState; +} + +/** + * State service is a always running service that exposes the current state of + * the wallet and RPC server. + */ +export interface State { + /** + * SubscribeState subscribes to the state of the wallet. The current wallet + * state will always be delivered immediately. + */ + subscribeState( + request?: DeepPartial, + onMessage?: (msg: SubscribeStateResponse) => void, + onError?: (err: Error) => void + ): void; + /** + * GetState returns the current wallet state without streaming further + * changes. + */ + getState(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/lnrpc.ts b/lib/types/proto/lnrpc.ts index 730b051..2ebca58 100644 --- a/lib/types/proto/lnrpc.ts +++ b/lib/types/proto/lnrpc.ts @@ -1,2 +1,3 @@ export * from './lnd/lightning'; +export * from './lnd/stateservice'; export * from './lnd/walletunlocker'; diff --git a/lib/types/proto/loop/client.ts b/lib/types/proto/loop/client.ts index 87104d2..97628cf 100644 --- a/lib/types/proto/loop/client.ts +++ b/lib/types/proto/loop/client.ts @@ -268,6 +268,10 @@ export enum StaticAddressLoopInSwapState { UNRECOGNIZED = 'UNRECOGNIZED' } +export interface StopDaemonRequest {} + +export interface StopDaemonResponse {} + export interface LoopOutRequest { /** Requested swap amount in sat. This does not include the swap and miner fee. */ amt: string; @@ -622,7 +626,12 @@ export interface OutTermsResponse { } export interface QuoteRequest { - /** The amount to swap in satoshis. */ + /** + * The amount to swap in satoshis. In the loop-in case this can either be taken + * from the connected lnd wallet or coin-selected from static address deposits. + * This is controlled by the select_deposits flag. If deposit_outpoints are + * specified, the coins are taken out of that. + */ amt: string; /** * The confirmation target that should be used either for the sweep of the @@ -660,8 +669,9 @@ export interface QuoteRequest { private: boolean; /** * Static address deposit outpoints that will be quoted for. This option only - * pertains to loop in swaps. Either this or the amt parameter can be set at - * the same time. + * pertains to loop in swaps. If the amt field is set as well the respective + * partial amount will be swapped. Cannot be used in conjunction with + * auto_select_deposits. */ depositOutpoints: string[]; /** @@ -669,6 +679,19 @@ export interface QuoteRequest { * be returned in the specified asset. */ assetInfo: AssetLoopOutRequest | undefined; + /** + * In the legacy loop-in case this field must be set to false. + * If set to true, the swap amount will be automatically selected from the + * static address deposits. If set to true, deposit_outpoints must be empty. + * This option only pertains to loop in swaps. + */ + autoSelectDeposits: boolean; + /** + * If set to true the server will immediately publish the swap in exchange for + * a higher fee. This can be useful if the client expects change from a swap. + * Note that this feature is only available for static address loop in swaps. + */ + fast: boolean; } export interface InQuoteResponse { @@ -687,6 +710,12 @@ export interface InQuoteResponse { cltvDelta: number; /** The confirmation target to be used to publish the on-chain HTLC. */ confTarget: number; + /** + * If the quote request was for a static address loop in and only contained + * deposit outpoints the quote response will return the total amount of the + * selected deposits. + */ + quotedAmt: string; } export interface OutQuoteResponse { @@ -947,6 +976,12 @@ export interface LiquidityParameters { * not be able to be batched with other swaps. */ fastSwapPublication: boolean; + /** + * A list of peers (their public keys) that should be excluded from the easy + * autoloop run. If set, channels connected to these peers won't be + * considered for easy autoloop swaps. + */ + easyAutoloopExcludedPeers: Uint8Array | string[]; } export interface LiquidityParameters_EasyAssetParamsEntry { @@ -1282,6 +1317,11 @@ export interface Deposit { * loop-in swap anymore. */ blocksUntilExpiry: string; + /** + * The swap hash of the swap that this deposit is part of. This field is only + * set if the deposit is part of a loop-in swap. + */ + swapHash: Uint8Array | string; } export interface StaticAddressWithdrawal { @@ -1320,6 +1360,8 @@ export interface StaticAddressLoopInSwap { * fees. */ paymentRequestAmountSatoshis: string; + /** The deposits that were used for this swap. */ + deposits: Deposit[]; } export interface StaticAddressLoopInRequest { @@ -1366,6 +1408,22 @@ export interface StaticAddressLoopInRequest { * side and the client can retry the swap with different parameters. */ paymentTimeoutSeconds: number; + /** + * The optional swap amount the client is attempting to swap. It can be + * provided in combination with the outpoints or separately. If provided with + * outpoints the client takes out this amount from the sum of provided + * outpoints and sends the change back to the static address. If the amount is + * provided without outpoints, the client will select deposits automatically. + * The coin selection strategy is simplified by sorting all available deposits + * in descending order by amount, and equal amounts in ascending order of + * blocks until expiry, and then selecting the largest deposits first until the + * amount is reached. The change will be sent back to the static address. If a + * subset of outpoints suffice to cover the specified amount the swap will be + * canceled to allow the user to safe on transaction fees. + */ + amount: string; + /** If set, request the server to use fast publication behavior. */ + fast: boolean; } export interface StaticAddressLoopInResponse { @@ -1402,6 +1460,20 @@ export interface StaticAddressLoopInResponse { * side and the client can retry the swap with different parameters. */ paymentTimeoutSeconds: number; + /** The deposits that are used for this swap. */ + usedDeposits: Deposit[]; + /** + * The amount that is being swapped (may be less than total deposit value if + * change is returned). + */ + swapAmount: string; + /** The change amount that will be returned to the static address. */ + change: string; + /** + * If set, indicates that the server was requested to use fast publication + * behavior. + */ + fast: boolean; } export interface AssetLoopOutRequest { @@ -1610,6 +1682,13 @@ export interface SwapClient { * GetInfo gets basic information about the loop daemon. */ getInfo(request?: DeepPartial): Promise; + /** + * loop: `stop` + * StopDaemon instructs the daemon to shut down gracefully. + */ + stopDaemon( + request?: DeepPartial + ): Promise; /** * loop: `getparams` * GetLiquidityParams gets the parameters that the daemon's liquidity manager diff --git a/lib/types/proto/peersrpc.ts b/lib/types/proto/peersrpc.ts new file mode 100644 index 0000000..643e1d0 --- /dev/null +++ b/lib/types/proto/peersrpc.ts @@ -0,0 +1 @@ +export * from './lnd/peersrpc/peers'; diff --git a/lib/types/proto/pool/auctioneerrpc/auctioneer.ts b/lib/types/proto/pool/auctioneerrpc/auctioneer.ts index 1d57f65..c4d7538 100644 --- a/lib/types/proto/pool/auctioneerrpc/auctioneer.ts +++ b/lib/types/proto/pool/auctioneerrpc/auctioneer.ts @@ -11,8 +11,6 @@ export enum ChannelType { * outputs that pay directly to the channel initiator (the seller). */ SCRIPT_ENFORCED_LEASE = 'SCRIPT_ENFORCED_LEASE', - /** SIMPLE_TAPROOT - A channel type that uses a Pay-to-Taproot output for the funding output. */ - SIMPLE_TAPROOT = 'SIMPLE_TAPROOT', UNRECOGNIZED = 'UNRECOGNIZED' } @@ -62,8 +60,6 @@ export enum OrderChannelType { * channel initiator/seller. */ ORDER_CHANNEL_TYPE_SCRIPT_ENFORCED = 'ORDER_CHANNEL_TYPE_SCRIPT_ENFORCED', - /** ORDER_CHANNEL_TYPE_SIMPLE_TAPROOT - A channel type that uses a Pay-to-Taproot output for the funding output. */ - ORDER_CHANNEL_TYPE_SIMPLE_TAPROOT = 'ORDER_CHANNEL_TYPE_SIMPLE_TAPROOT', UNRECOGNIZED = 'UNRECOGNIZED' } diff --git a/lib/types/proto/schema.ts b/lib/types/proto/schema.ts index 63be91f..cbb0060 100644 --- a/lib/types/proto/schema.ts +++ b/lib/types/proto/schema.ts @@ -16,8 +16,10 @@ export const serviceNames = { invoicesrpc: { Invoices: 'invoicesrpc.Invoices' }, lnrpc: { Lightning: 'lnrpc.Lightning', + State: 'lnrpc.State', WalletUnlocker: 'lnrpc.WalletUnlocker' }, + peersrpc: { Peers: 'peersrpc.Peers' }, routerrpc: { Router: 'routerrpc.Router' }, signrpc: { Signer: 'signrpc.Signer' }, walletrpc: { WalletKit: 'walletrpc.WalletKit' }, @@ -30,6 +32,7 @@ export const serviceNames = { Trader: 'poolrpc.Trader' }, assetwalletrpc: { AssetWallet: 'assetwalletrpc.AssetWallet' }, + authmailboxrpc: { Mailbox: 'authmailboxrpc.Mailbox' }, mintrpc: { Mint: 'mintrpc.Mint' }, priceoraclerpc: { PriceOracle: 'priceoraclerpc.PriceOracle' }, rfqrpc: { Rfq: 'rfqrpc.Rfq' }, @@ -73,10 +76,12 @@ export const subscriptionMethods = [ 'routerrpc.Router.SendPayment', 'routerrpc.Router.TrackPayment', 'routerrpc.Router.HtlcInterceptor', + 'lnrpc.State.SubscribeState', 'looprpc.SwapClient.Monitor', 'poolrpc.ChannelAuctioneer.SubscribeBatchAuction', 'poolrpc.ChannelAuctioneer.SubscribeSidecar', 'poolrpc.HashMail.RecvStream', + 'authmailboxrpc.Mailbox.ReceiveMessages', 'lnrpc.Lightning.SubscribeTransactions', 'lnrpc.Lightning.SubscribePeerEvents', 'lnrpc.Lightning.SubscribeChannelEvents', diff --git a/lib/types/proto/tapd/assetwalletrpc/assetwallet.ts b/lib/types/proto/tapd/assetwalletrpc/assetwallet.ts index 64860e1..e74dc3a 100644 --- a/lib/types/proto/tapd/assetwalletrpc/assetwallet.ts +++ b/lib/types/proto/tapd/assetwalletrpc/assetwallet.ts @@ -1,10 +1,11 @@ /* eslint-disable */ import type { - OutPoint, + AddressWithAmount, KeyDescriptor, ScriptKey, SendAssetResponse } from '../taprootassets'; +import type { OutPoint } from '../tapcommon'; export enum CoinSelectType { /** @@ -68,10 +69,23 @@ export interface TxTemplate { */ inputs: PrevId[]; /** - * A map of all Taproot Asset addresses mapped to the anchor transaction's - * output index that should be sent to. + * DEPRECATED: A map of all Taproot Asset addresses that should be sent to. + * The keys are the Taproot Asset addresses in human-readable form, and the + * values are IGNORED and should not be set (use the addresses_with_amounts + * field below instead). The recipients map and addresses_with_amounts list + * are mutually exclusive, meaning that if addresses_with_amounts is set, then + * recipients must be empty, and vice versa. */ recipients: { [key: string]: string }; + /** + * A list of addresses and the amounts of asset units to send to them. This + * must be used for V2 TAP addresses that don't specify an amount in the + * address itself and allow the sender to choose the amount to send. The + * recipients and addresses_with_amounts lists are mutually exclusive, + * meaning that if addresses_with_amounts is set, then recipients must be + * empty, and vice versa. + */ + addressesWithAmounts: AddressWithAmount[]; } export interface TxTemplate_RecipientsEntry { @@ -255,18 +269,25 @@ export interface PublishAndLogRequest { } export interface NextInternalKeyRequest { + /** The key family to derive the next internal key for. */ keyFamily: number; } export interface NextInternalKeyResponse { + /** The full key descriptor of the internal key that was derived. */ internalKey: KeyDescriptor | undefined; } export interface NextScriptKeyRequest { + /** The key family to derive the next script key for. */ keyFamily: number; } export interface NextScriptKeyResponse { + /** + * The full script key information that was derived, including the + * internal key and the tweaked script key. + */ scriptKey: ScriptKey | undefined; } @@ -279,6 +300,7 @@ export interface QueryInternalKeyRequest { } export interface QueryInternalKeyResponse { + /** The full key descriptor of the internal key that was queried. */ internalKey: KeyDescriptor | undefined; } @@ -292,12 +314,25 @@ export interface QueryScriptKeyRequest { } export interface QueryScriptKeyResponse { + /** + * The full script key information that was queried, including the + * internal key and the tweaked script key. + */ scriptKey: ScriptKey | undefined; } export interface ProveAssetOwnershipRequest { + /** + * The asset ID of the asset to prove ownership of. This is the 32-byte + * asset ID that identifies a particular asset or tranche of assets. + */ assetId: Uint8Array | string; + /** The script key that is used to spend the asset. */ scriptKey: Uint8Array | string; + /** + * The outpoint of the asset UTXO that is being proven to be owned by the + * prover. + */ outpoint: OutPoint | undefined; /** * An optional 32-byte challenge that may be used to bind the generated @@ -312,6 +347,10 @@ export interface ProveAssetOwnershipResponse { } export interface VerifyAssetOwnershipRequest { + /** + * The full ownership proof that was generated, including the witness data + * that contains the proving signature. + */ proofWithWitness: Uint8Array | string; /** * An optional 32-byte challenge that may be used to check the ownership @@ -322,6 +361,7 @@ export interface VerifyAssetOwnershipRequest { } export interface VerifyAssetOwnershipResponse { + /** Whether the ownership proof is valid or not. */ validProof: boolean; /** The outpoint the proof commits to. */ outpoint: OutPoint | undefined; @@ -343,10 +383,15 @@ export interface RemoveUTXOLeaseRequest { export interface RemoveUTXOLeaseResponse {} export interface DeclareScriptKeyRequest { + /** The script key the wallet should be informed about. */ scriptKey: ScriptKey | undefined; } export interface DeclareScriptKeyResponse { + /** + * The script key that was declared, including the internal key and the + * tweaked script key. + */ scriptKey: ScriptKey | undefined; } @@ -444,6 +489,7 @@ export interface AssetWallet { request?: DeepPartial ): Promise; /** + * `tapcli: assets removelease` * RemoveUTXOLease removes the lease/lock/reservation of the given managed * UTXO. */ diff --git a/lib/types/proto/tapd/authmailboxrpc/mailbox.ts b/lib/types/proto/tapd/authmailboxrpc/mailbox.ts new file mode 100644 index 0000000..5f2c818 --- /dev/null +++ b/lib/types/proto/tapd/authmailboxrpc/mailbox.ts @@ -0,0 +1,289 @@ +/* eslint-disable */ +import type { OutPoint } from '../tapcommon'; + +/** + * Represents the Merkle proof hashes needed to link a transaction to the Merkle + * root within a Bitcoin block header. + */ +export interface MerkleProof { + /** + * List of sibling hashes in the Merkle path, ordered from the transaction's + * sibling up towards the root. Each hash is typically 32 bytes. + */ + siblingHashes: Uint8Array | string[]; + /** + * The bitmask indicating the direction (left/right) of each sibling hash + * in the Merkle tree. Each bit corresponds to a sibling hash in the + * sibling_hashes list. 0 indicates left, 1 indicates right. + */ + bits: boolean[]; +} + +/** + * Encapsulates the full proof required for sender authentication, demonstrating + * that a specific P2TR transaction output was included in a Bitcoin block. To + * prove knowledge of the claimed output, the proof must include the output's + * internal key and, optionally, the Taproot Merkle root. + */ +export interface BitcoinMerkleInclusionProof { + /** + * The raw Bitcoin transaction bytes, in standard Bitcoin serialization + * format, containing the outpoint being claimed. The server will hash this + * to get the TXID. + */ + rawTxData: Uint8Array | string; + /** + * The raw block header bytes (typically 80 bytes) of the block in which the + * transaction was mined. Contains the Merkle root against which the proof + * is verified. + */ + rawBlockHeaderData: Uint8Array | string; + /** + * The height at which the block was mined. This is used to determine the + * block's validity and to ensure the transaction is not too old. + */ + blockHeight: number; + /** + * The Merkle path proving the transaction's inclusion in the block header's + * Merkle root. + */ + merkleProof: MerkleProof | undefined; + /** + * The specific output within the provided transaction being claimed as the + * proof "token". The output at the given index must be a P2TR output. + * The server must verify that the txid_hex matches the hash of the provided + * transaction data, and that this specific outpoint index exists in the + * transaction. + */ + claimedOutpoint: OutPoint | undefined; + /** + * The Taproot internal key used to construct the P2TR output that is + * claimed by the outpoint above. Must be provided alongside the Taproot + * Merkle root to prove knowledge of the output's construction. + */ + internalKey: Uint8Array | string; + /** + * The Taproot Merkle root, if applicable. This, alongside the internal key, + * is used to prove knowledge of the output's construction. If this is not + * provided (empty or nil), a BIP-0086 construction is assumed. + */ + merkleRoot: Uint8Array | string; +} + +/** Represents a single message as stored and retrieved from the mailbox. */ +export interface MailboxMessage { + /** The unique ID assigned to the message by the server upon storage. */ + messageId: string; + /** The ECIES encrypted message payload, intended for the receiver. */ + encryptedPayload: Uint8Array | string; + /** Timestamp (Unix epoch seconds) when the message arrived at the server. */ + arrivalTimestamp: string; +} + +/** Represents a list of messages. */ +export interface MailboxMessages { + /** The list of mailbox messages. */ + messages: MailboxMessage[]; +} + +/** Request message for the SendMessage RPC. */ +export interface SendMessageRequest { + /** + * The public key identifier of the intended receiver (ReceiverID), encoded + * as the raw bytes of the compressed public key. + */ + receiverId: Uint8Array | string; + /** The ECIES encrypted message payload. */ + encryptedPayload: Uint8Array | string; + /** + * The Bitcoin Merkle Inclusion Proof used as the sender's + * authentication. The server MUST perform full validation of this + * proof: + * 1. Verify claimed_outpoint.txid_hex matches hash(raw_tx_data). + * 2. Verify claimed_outpoint.index is valid for the transaction. + * 3. Verify merkle_proof connects the transaction hash to the + * raw_block_header_data's Merkle root. + * 4. Verify block_header validity (e.g., PoW, potentially chain + * context). + * 5. Ensure the claimed_outpoint has not been used previously (check + * used_proofs table). + */ + txProof: BitcoinMerkleInclusionProof | undefined; +} + +/** Response message for the SendMessage RPC. */ +export interface SendMessageResponse { + /** The unique ID assigned to the stored message by the server. */ + messageId: string; +} + +/** + * Wrapper message for requests sent FROM the client TO the server during the + * ReceiveMessages stream. + */ +export interface ReceiveMessagesRequest { + /** + * The initial parameters sent by the client to start receiving + * messages. + */ + init: InitReceive | undefined; + /** The client's signature in response to the server's challenge. */ + authSig: AuthSignature | undefined; +} + +/** Carries the initial parameters from the client to start receiving messages. */ +export interface InitReceive { + /** + * The public key identifier of the receiver of the messages that should be + * received through a message receive stream, encoded as the raw bytes of + * the compressed public key. + */ + receiverId: Uint8Array | string; + /** + * The exclusive start message ID, meaning messages with this ID or higher + * will be included in the response. This allows the client to resume + * receiving messages from a specific point without missing any. One of + * start_message_id_exclusive, start_block_height_inclusive or + * start_timestamp_exclusive must be at their non-default values for any + * existing messages to be returned! + */ + startMessageIdExclusive: string; + /** + * The inclusive start block height, meaning messages from this block height + * or higher will be included in the response. This allows the client to + * filter messages based on the block height at which they were produced. + * One of start_message_id_exclusive, start_block_height_inclusive or + * start_timestamp_exclusive must be at their non-default values for any + * existing messages to be returned! + */ + startBlockHeightInclusive: number; + /** + * The exclusive start timestamp in Unix epoch seconds, meaning messages + * with a timestamp strictly greater than this value will be included in the + * response. This allows the client to filter messages based on their + * arrival time at the server. One of start_message_id_exclusive, + * start_block_height_inclusive or start_timestamp_exclusive must be at + * their non-default values for any existing messages to be returned! + */ + startTimestampExclusive: string; +} + +/** Carries the client's signature in response to the server's challenge. */ +export interface AuthSignature { + /** + * The client's Schnorr signature over the challenge hash provided by + * the server. + */ + signature: Uint8Array | string; +} + +/** + * Wrapper message for responses sent FROM the server TO the client + * during the ReceiveMessages stream. + */ +export interface ReceiveMessagesResponse { + /** + * The challenge sent by the server to the client, which the client + * must sign to prove ownership of the receiver's public key. + */ + challenge: Challenge | undefined; + /** + * A successful authentication response, indicating the client has + * successfully signed the challenge and is now authenticated to receive + * messages. + */ + authSuccess: boolean | undefined; + /** + * A list of mailbox messages sent to the client. This will be + * sent after the client has successfully authenticated by signing the + * challenge. The client should expect a stream of these messages + * until the server sends an EndOfStream message. + */ + messages: MailboxMessages | undefined; + /** An EndOfStream message indicating that the server is shutting down. */ + eos: EndOfStream | undefined; +} + +/** Carries the challenge hash sent by the server to the client. */ +export interface Challenge { + /** + * The challenge hash that the client must sign to prove ownership of the + * receiver's public key. + */ + challengeHash: Uint8Array | string; +} + +/** + * An empty message used to explicitly signal the normal end of the message + * stream. + */ +export interface EndOfStream {} + +/** Request message for the MailboxInfo RPC. */ +export interface MailboxInfoRequest {} + +/** Response message for the MailboxInfo RPC. */ +export interface MailboxInfoResponse { + /** The current server time in Unix epoch seconds. */ + serverTime: string; + /** The number of messages currently stored on the server. */ + messageCount: string; +} + +/** + * Service definition for the authenticated mailbox. This service allows sending + * messages (authenticated by UTXO proof) and receiving messages (authenticated + * via a challenge-response handshake). + */ +export interface Mailbox { + /** + * Sends a single message to a receiver's mailbox. Requires a valid, unused + * Bitcoin P2TR transaction outpoint as proof of uniqueness, included in a + * block as proof of work. + */ + sendMessage( + request?: DeepPartial + ): Promise; + /** + * Initiates a bidirectional stream to receive messages for a specific + * receiver. This stream implements the challenge-response handshake required + * for receiver authentication before messages are delivered. + * + * Expected flow: + * 1. Client -> Server: ReceiveMessagesRequest(init = InitReceive{...}) + * 2. Server -> Client: ReceiveMessagesResponse(challenge = Challenge{...}) + * 3. Client -> Server: ReceiveMessagesRequest(auth_sig = AuthSignature{...}) + * 4. Server -> Client: [Stream of ReceiveMessagesResponse( + * message = MailboxMessage{...} + * )] + * 5. Server -> Client: ReceiveMessagesResponse(eos = EndOfStream{}) + */ + receiveMessages( + request?: DeepPartial, + onMessage?: (msg: ReceiveMessagesResponse) => void, + onError?: (err: Error) => void + ): void; + /** Returns basic server information. */ + mailboxInfo( + 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/lightning.ts b/lib/types/proto/tapd/lightning.ts index e89b73c..fbdf460 100644 --- a/lib/types/proto/tapd/lightning.ts +++ b/lib/types/proto/tapd/lightning.ts @@ -1236,6 +1236,7 @@ export interface Peer { */ errors: TimestampedError[]; /** + * This field is populated when the peer has at least one channel with us. * 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 @@ -1243,6 +1244,7 @@ export interface Peer { */ flapCount: number; /** + * This field is populated when the peer has at least one channel with us. * 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. */ @@ -1400,12 +1402,6 @@ export interface Chain { network: string; } -export interface ConfirmationUpdate { - blockSha: Uint8Array | string; - blockHeight: number; - numConfsLeft: number; -} - export interface ChannelOpenUpdate { channelPoint: ChannelPoint | undefined; } @@ -2123,6 +2119,27 @@ export interface PendingChannelsResponse_PendingOpenChannel { * fully operational. */ fundingExpiryBlocks: number; + /** + * The number of blocks remaining until the channel status changes from + * pending to active. A value of 0 indicates that the channel is now + * active. + * + * "Active" here means both channel peers have the channel marked OPEN + * and can immediately start using it. For public channels, this does + * not imply a channel_announcement has been gossiped. It only becomes + * public on the network after 6 on‐chain confirmations. + * See BOLT07 "Routing Gossip": + * https://github.com/lightning/bolts/blob/master/07-routing-gossip.md + * + * ZeroConf channels bypass the pending state entirely: they are marked + * active immediately upon creation, so they never show up as "pending". + */ + confirmationsUntilActive: number; + /** + * The confirmation height records the block height at which the funding + * transaction was first confirmed. + */ + confirmationHeight: number; } export interface PendingChannelsResponse_WaitingCloseChannel { @@ -2220,6 +2237,7 @@ export interface ChannelEventUpdate { inactiveChannel: ChannelPoint | undefined; pendingOpenChannel: PendingUpdate | undefined; fullyResolvedChannel: ChannelPoint | undefined; + channelFundingTimeout: ChannelPoint | undefined; type: ChannelEventUpdate_UpdateType; } @@ -2230,6 +2248,7 @@ export enum ChannelEventUpdate_UpdateType { INACTIVE_CHANNEL = 'INACTIVE_CHANNEL', PENDING_OPEN_CHANNEL = 'PENDING_OPEN_CHANNEL', FULLY_RESOLVED_CHANNEL = 'FULLY_RESOLVED_CHANNEL', + CHANNEL_FUNDING_TIMEOUT = 'CHANNEL_FUNDING_TIMEOUT', UNRECOGNIZED = 'UNRECOGNIZED' } @@ -2391,8 +2410,10 @@ export interface QueryRoutesRequest { */ 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. + * 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. + * + * @deprecated */ outgoingChanId: string; /** The pubkey of the last hop of the route. If empty, any hop may be used. */ @@ -2420,6 +2441,11 @@ export interface QueryRoutesRequest { * only, to 1 to optimize for reliability only or a value inbetween for a mix. */ timePref: number; + /** + * The channel ids of the channels allowed for the first hop. If empty, any + * channel may be used. + */ + outgoingChanIds: string[]; } export interface QueryRoutesRequest_DestCustomRecordsEntry { @@ -2628,6 +2654,11 @@ export interface NodeInfoRequest { pubKey: string; /** If true, will include all known channels associated with the node. */ includeChannels: boolean; + /** + * If true, will include announcements' signatures into ChannelEdge. + * Depends on include_channels. + */ + includeAuthProof: boolean; } export interface NodeInfo { @@ -2686,7 +2717,10 @@ export interface RoutingPolicy { disabled: boolean; maxHtlcMsat: string; lastUpdate: number; - /** Custom channel update tlv records. */ + /** + * Custom channel update tlv records. These are customized fields that are + * not defined by LND and cannot be extracted. + */ customRecords: { [key: string]: Uint8Array | string }; inboundFeeBaseMsat: number; inboundFeeRateMilliMsat: number; @@ -2697,6 +2731,36 @@ export interface RoutingPolicy_CustomRecordsEntry { value: Uint8Array | string; } +/** + * ChannelAuthProof is the authentication proof (the signature portion) for a + * channel. Using the four signatures contained in the struct, and some + * auxiliary knowledge (the funding script, node identities, and outpoint) nodes + * on the network are able to validate the authenticity and existence of a + * channel. + */ +export interface ChannelAuthProof { + /** + * node_sig1 are the raw bytes of the first node signature encoded + * in DER format. + */ + nodeSig1: Uint8Array | string; + /** + * bitcoin_sig1 are the raw bytes of the first bitcoin signature of the + * MultiSigKey key of the channel encoded in DER format. + */ + bitcoinSig1: Uint8Array | string; + /** + * node_sig2 are the raw bytes of the second node signature encoded + * in DER format. + */ + nodeSig2: Uint8Array | string; + /** + * bitcoin_sig2 are the raw bytes of the second bitcoin signature of the + * MultiSigKey key of the channel encoded in DER format. + */ + bitcoinSig2: Uint8Array | string; +} + /** * A fully authenticated channel along with all its unique attributes. * Once an authenticated channel announcement has been processed on the network, @@ -2721,6 +2785,14 @@ export interface ChannelEdge { node2Policy: RoutingPolicy | undefined; /** Custom channel announcement tlv records. */ customRecords: { [key: string]: Uint8Array | string }; + /** + * Authentication proof for this channel. This proof contains a set of + * signatures binding four identities, which attests to the legitimacy of + * the advertised channel. This only is available for advertised channels. + * This field is not filled by default. Pass include_auth_proof flag to + * DescribeGraph, GetNodeInfo or GetChanInfo to get this data. + */ + authProof: ChannelAuthProof | undefined; } export interface ChannelEdge_CustomRecordsEntry { @@ -2735,6 +2807,8 @@ export interface ChannelGraphRequest { * channels, and public channels that are not yet announced to the network. */ includeUnannounced: boolean; + /** If true, will include announcements' signatures into ChannelEdge. */ + includeAuthProof: boolean; } /** Returns a new instance of the directed channel graph. */ @@ -2785,6 +2859,8 @@ export interface ChanInfoRequest { * chan_id is specified, this field is ignored. */ chanPoint: string; + /** If true, will include announcements' signatures into ChannelEdge. */ + includeAuthProof: boolean; } export interface NetworkInfoRequest {} @@ -3181,6 +3257,11 @@ export interface BlindedPathConfig { * blinded paths. */ nodeOmissionList: Uint8Array | string[]; + /** + * The chained channels list specified via channel id (separated by commas), + * starting from a channel owned by the receiver node. + */ + incomingChannelList: string[]; } /** Details of an HTLC that paid to an invoice */ @@ -3345,6 +3426,16 @@ export interface InvoiceSubscription { settleIndex: string; } +export interface DelCanceledInvoiceReq { + /** Invoice payment hash to delete. */ + invoiceHash: string; +} + +export interface DelCanceledInvoiceResp { + /** The status of the delete operation. */ + status: string; +} + export interface Payment { /** The payment hash */ paymentHash: string; @@ -3749,6 +3840,16 @@ export interface ForwardingHistoryRequest { * forwarding event. */ peerAliasLookup: boolean; + /** + * List of incoming channel ids to filter htlcs received from a + * particular channel + */ + incomingChanIds: string[]; + /** + * List of outgoing channel ids to filter htlcs being forwarded to a + * particular channel + */ + outgoingChanIds: string[]; } export interface ForwardingEvent { @@ -3799,6 +3900,16 @@ export interface ForwardingEvent { peerAliasIn: string; /** The peer alias of the outgoing channel. */ peerAliasOut: string; + /** + * The ID of the incoming HTLC in the payment circuit. This field is + * optional and is unset for forwarding events happened before v0.20. + */ + incomingHtlcId?: string | undefined; + /** + * The ID of the outgoing HTLC in the payment circuit. This field is + * optional and may be unset for legacy forwarding events. + */ + outgoingHtlcId?: string | undefined; } export interface ForwardingHistoryResponse { @@ -4087,9 +4198,42 @@ export interface Op { } export interface CheckMacPermRequest { + /** + * The macaroon to check permissions for, serialized in binary format. For + * a macaroon to be valid, it must have been issued by lnd, must succeed all + * caveat conditions, and must contain all of the permissions specified in + * the permissions field. + */ macaroon: Uint8Array | string; + /** + * The list of permissions the macaroon should be checked against. Only if + * the macaroon contains all of these permissions, it is considered valid. + * If the list of permissions given is empty, then the macaroon is + * considered valid only based on issuance authority and caveat validity. + * An empty list of permissions is therefore equivalent to saying "skip + * checking permissions" (unless check_default_perms_from_full_method is + * specified). + */ permissions: MacaroonPermission[]; + /** + * The RPC method to check the macaroon against. This is only used if there + * are custom `uri:./` permissions in + * the permission list above. To check a macaroon against the list of + * permissions of a certain RPC method, query the `ListPermissions` RPC + * first, extract the permissions for the method, and then pass them in the + * `permissions` field above. + */ fullMethod: string; + /** + * If this field is set to true, then the permissions list above MUST be + * empty. The default permissions for the provided fullMethod will be used + * to check the macaroon. This is equivalent to looking up the permissions + * for a method in the `ListPermissions` RPC and then calling this RPC with + * the permission list returned from that call. Without this flag, the list + * of permissions must be non-empty for the check to actually perform a + * permission check. + */ + checkDefaultPermsFromFullMethod: boolean; } export interface CheckMacPermResponse { @@ -4675,6 +4819,14 @@ export interface Lightning { onMessage?: (msg: Invoice) => void, onError?: (err: Error) => void ): void; + /** + * lncli: `deletecanceledinvoice` + * DeleteCanceledInvoice removes a canceled invoice from the database. If the + * invoice is not in the canceled state, an error will be returned. + */ + deleteCanceledInvoice( + request?: DeepPartial + ): Promise; /** * lncli: `decodepayreq` * DecodePayReq takes an encoded payment request string and attempts to decode @@ -4913,9 +5065,10 @@ export interface Lightning { 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 checks whether the provided macaroon contains all + * the provided permissions. If the macaroon is valid (e.g. all caveats are + * satisfied), and all permissions provided in the request are met, then + * this RPC returns true. */ checkMacaroonPermissions( request?: DeepPartial diff --git a/lib/types/proto/tapd/mintrpc/mint.ts b/lib/types/proto/tapd/mintrpc/mint.ts index 3fc76e9..77213f0 100644 --- a/lib/types/proto/tapd/mintrpc/mint.ts +++ b/lib/types/proto/tapd/mintrpc/mint.ts @@ -166,19 +166,16 @@ export interface MintAsset { */ externalGroupKey: ExternalKey | undefined; /** - * Enabling this flag allows the creation of universe commitments for a new - * asset group. + * Enables the supply commitments feature for a new asset group. * - * Universe commitments are minter-controlled, on-chain attestations that - * anchor and verify the state of an asset group. + * Supply commitments are minter‑controlled, on‑chain attestations that + * anchor and verify the evolving aggregate supply state of an asset group. * - * This flag imposes restrictions on the minting process by limiting the batch - * to assets within the same universe, meaning they share the same group key. - * This option is applicable only for the creation of a new asset group - * (i.e., the first minting tranche of an asset group) and ensures that the - * batch is limited to a single asset group. + * When enabled, the batch must be a single asset group (all assets share the + * same group key). Valid only for creating a new asset group (the first + * minting tranche). */ - universeCommitments: boolean; + enableSupplyCommitments: boolean; } export interface MintAssetRequest { diff --git a/lib/types/proto/tapd/priceoraclerpc/price_oracle.ts b/lib/types/proto/tapd/priceoraclerpc/price_oracle.ts index f557795..3a3bed3 100644 --- a/lib/types/proto/tapd/priceoraclerpc/price_oracle.ts +++ b/lib/types/proto/tapd/priceoraclerpc/price_oracle.ts @@ -8,6 +8,75 @@ export enum TransactionType { UNRECOGNIZED = 'UNRECOGNIZED' } +/** + * Intent is an enum informing the price oracle about the intent of the price + * rate query. This is used to provide context for the asset rates being + * requested, allowing the price oracle to tailor the response based on the + * specific use case, such as paying an invoice or receiving a payment and the + * different stages involved in those. + */ +export enum Intent { + /** + * INTENT_UNSPECIFIED - INTENT_UNSPECIFIED is used to indicate that the intent of the price rate + * query is not specified. This is the fallback default value and should not + * be used in production code. It is primarily used for backward + * compatibility with older versions of the protocol that did not include + * intent information. + */ + INTENT_UNSPECIFIED = 'INTENT_UNSPECIFIED', + /** + * INTENT_PAY_INVOICE_HINT - INTENT_PAY_INVOICE_HINT is used to indicate that the user is requesting + * a price rate hint for paying an invoice. This is typically used by the + * payer of an invoice to provide a suggestion of the expected asset rate to + * the RFQ peer (edge node) that will determine the actual rate for the + * payment. + */ + INTENT_PAY_INVOICE_HINT = 'INTENT_PAY_INVOICE_HINT', + /** + * INTENT_PAY_INVOICE - INTENT_PAY_INVOICE is used to indicate that a peer wants to pay an + * invoice with assets. This is typically used by the edge node that + * facilitates the swap from assets to BTC for the payer of an invoice. This + * intent is used to provide the actual asset rate for the payment, which + * may differ from the hint provided by the payer. + */ + INTENT_PAY_INVOICE = 'INTENT_PAY_INVOICE', + /** + * INTENT_PAY_INVOICE_QUALIFY - INTENT_PAY_INVOICE_QUALIFY is used to indicate that the payer of an + * invoice has received an asset rate from their RFQ peer (edge node) and is + * qualifying the rate for the payment. This is typically used by the payer + * of an invoice to ensure that the asset rate provided by their peer (edge + * node) is acceptable before proceeding with the payment. + */ + INTENT_PAY_INVOICE_QUALIFY = 'INTENT_PAY_INVOICE_QUALIFY', + /** + * INTENT_RECV_PAYMENT_HINT - INTENT_RECV_PAYMENT_HINT is used to indicate that the user is requesting + * a price rate hint for receiving a payment through an invoice. This is + * typically used by the creator of an invoice to provide a suggestion of + * the expected asset rate to the RFQ peer (edge node) that will determine + * the actual rate used for creating an invoice. + */ + INTENT_RECV_PAYMENT_HINT = 'INTENT_RECV_PAYMENT_HINT', + /** + * INTENT_RECV_PAYMENT - INTENT_RECV_PAYMENT is used to indicate that a peer wants to create an + * invoice to receive a payment with assets. This is typically used by the + * edge node that facilitates the swap from BTC to assets for the receiver + * of a payment. This intent is used to provide the actual asset rate for + * the invoice creation, which may differ from the hint provided by the + * receiver. + */ + INTENT_RECV_PAYMENT = 'INTENT_RECV_PAYMENT', + /** + * INTENT_RECV_PAYMENT_QUALIFY - INTENT_RECV_PAYMENT_QUALIFY is used to indicate that the creator of an + * invoice received an asset rate from their RFQ peer (edge node) and is + * qualifying the rate for the creation of the invoice. This is typically + * used by the creator of an invoice to ensure that the asset rate provided + * by their peer (edge node) is acceptable before proceeding with creating + * the invoice. + */ + INTENT_RECV_PAYMENT_QUALIFY = 'INTENT_RECV_PAYMENT_QUALIFY', + UNRECOGNIZED = 'UNRECOGNIZED' +} + /** * FixedPoint is a scaled integer representation of a fractional number. * @@ -131,6 +200,35 @@ export interface QueryAssetRatesRequest { * transaction, intended to provide guidance on expected pricing. */ assetRatesHint: AssetRates | undefined; + /** + * intent informs the price oracle about the stage of the payment flow that + * lead to the price rate query. This is used to provide context for the + * asset rates being requested, allowing the price oracle to tailor the + * response based on the specific use case, such as paying an invoice or + * receiving a payment and the different stages involved in those. This + * field will only be set by tapd v0.7.0 and later. + */ + intent: Intent; + /** + * counterparty_id is the 33-byte public key of the peer that is on the + * opposite side of the transaction. This field will only be set by tapd + * v0.7.0 and later and only if the user initiating the transaction (sending + * a payment or creating an invoice) opted in to sharing their peer ID with + * the price oracle. + */ + counterpartyId: Uint8Array | string; + /** + * metadata is an optional text field that can be used to provide + * additional metadata about the transaction to the price oracle. This can + * include information about the wallet end user that initiated the + * transaction, or any authentication information that the price oracle + * can use to give out a more accurate (or discount) asset rate. Though not + * verified or enforced by tapd, the suggested format for this field is a + * JSON string. This field is optional and can be left empty if no metadata + * is available. The maximum length of this field is 32'768 bytes. This + * field will only be set by tapd v0.7.0 and later. + */ + metadata: string; } /** diff --git a/lib/types/proto/tapd/rfqrpc/rfq.ts b/lib/types/proto/tapd/rfqrpc/rfq.ts index edee946..0c5e78e 100644 --- a/lib/types/proto/tapd/rfqrpc/rfq.ts +++ b/lib/types/proto/tapd/rfqrpc/rfq.ts @@ -82,10 +82,7 @@ export interface AddAssetBuyOrderRequest { 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. - */ + /** 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 @@ -99,6 +96,17 @@ export interface AddAssetBuyOrderRequest { * scenarios. */ skipAssetChannelCheck: boolean; + /** + * An optional text field that can be used to provide additional metadata + * about the buy order to the price oracle. This can include information + * about the wallet end user that initiated the transaction, or any + * authentication information that the price oracle can use to give out a + * more accurate (or discount) asset rate. Though not verified or enforced + * by tapd, the suggested format for this field is a JSON string. + * This field is optional and can be left empty if no metadata is available. + * The maximum length of this field is 32'768 bytes. + */ + priceOracleMetadata: string; } export interface AddAssetBuyOrderResponse { @@ -129,10 +137,7 @@ export interface AddAssetSellOrderRequest { 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. - */ + /** 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 @@ -146,6 +151,17 @@ export interface AddAssetSellOrderRequest { * scenarios. */ skipAssetChannelCheck: boolean; + /** + * An optional text field that can be used to provide additional metadata + * about the sell order to the price oracle. This can include information + * about the wallet end user that initiated the transaction, or any + * authentication information that the price oracle can use to give out a + * more accurate (or discount) asset rate. Though not verified or enforced + * by tapd, the suggested format for this field is a JSON string. + * This field is optional and can be left empty if no metadata is available. + * The maximum length of this field is 32'768 bytes. + */ + priceOracleMetadata: string; } export interface AddAssetSellOrderResponse { @@ -186,6 +202,17 @@ export interface AddAssetBuyOfferResponse {} export interface QueryPeerAcceptedQuotesRequest {} +export interface AssetSpec { + /** The 32-byte asset ID specified as raw bytes. */ + id: Uint8Array | string; + /** + * The 32-byte asset group public key, serialized in BIP340 format. + * BIP340 defines a canonical encoding for Schnorr public keys. + * This field is serialized using schnorr.SerializePubKey. + */ + groupPubKey: Uint8Array | string; +} + export interface PeerAcceptedBuyQuote { /** Quote counterparty peer. */ peer: string; @@ -217,6 +244,16 @@ export interface PeerAcceptedBuyQuote { * HTLC to be above the dust limit. */ minTransportableUnits: string; + /** + * An optional user-provided text field used to provide additional metadata + * about the buy order to the price oracle. This can include information + * about the wallet end user that initiated the transaction, or any + * authentication information that the price oracle can use to give out a + * more accurate (or discount) asset rate. + */ + priceOracleMetadata: string; + /** The subject asset specifier. */ + assetSpec: AssetSpec | undefined; } export interface PeerAcceptedSellQuote { @@ -246,6 +283,16 @@ export interface PeerAcceptedSellQuote { * milli-satoshis. */ minTransportableMsat: string; + /** + * An optional user-provided text field used to provide additional metadata + * about the sell order to the price oracle. This can include information + * about the wallet end user that initiated the transaction, or any + * authentication information that the price oracle can use to give out a + * more accurate (or discount) asset rate. + */ + priceOracleMetadata: string; + /** The subject asset specifier. */ + assetSpec: AssetSpec | undefined; } /** diff --git a/lib/types/proto/tapd/routerrpc/router.ts b/lib/types/proto/tapd/routerrpc/router.ts index 66add01..14e211f 100644 --- a/lib/types/proto/tapd/routerrpc/router.ts +++ b/lib/types/proto/tapd/routerrpc/router.ts @@ -846,6 +846,16 @@ export interface DeleteAliasesResponse { aliasMaps: AliasMap[]; } +export interface FindBaseAliasRequest { + /** The alias we want to look up the base scid for. */ + alias: string; +} + +export interface FindBaseAliasResponse { + /** The base scid that resulted from the base scid look up. */ + base: string; +} + /** * Router is a service that offers advanced interaction with the router * subsystem of the daemon. @@ -1053,6 +1063,13 @@ export interface Router { xDeleteLocalChanAliases( request?: DeepPartial ): Promise; + /** + * XFindBaseLocalChanAlias is an experimental API that looks up the base scid + * for a local chan alias that was registered during the current runtime. + */ + xFindBaseLocalChanAlias( + request?: DeepPartial + ): Promise; } type Builtin = diff --git a/lib/types/proto/tapd/tapchannelrpc/tapchannel.ts b/lib/types/proto/tapd/tapchannelrpc/tapchannel.ts index 0c6a7af..ce47584 100644 --- a/lib/types/proto/tapd/tapchannelrpc/tapchannel.ts +++ b/lib/types/proto/tapd/tapchannelrpc/tapchannel.ts @@ -70,6 +70,7 @@ export interface RouterSendPaymentData_AssetAmountsEntry { } export interface EncodeCustomRecordsRequest { + /** The custom records to encode for a payment request. */ routerSendPayment: RouterSendPaymentData | undefined; } @@ -101,8 +102,8 @@ export interface SendPaymentRequest { 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. + * out the assets and converting them to satoshis. If set, only a quote with + * this peer may be negotiated to carry out the payment. */ peerPubkey: Uint8Array | string; /** @@ -135,6 +136,26 @@ export interface SendPaymentRequest { * Mutually exclusive to asset_id. */ groupKey: Uint8Array | string; + /** + * An optional text field that can be used to provide additional metadata + * about the payment to the price oracle. This can include information + * about the wallet end user that initiated the transaction, or any + * authentication information that the price oracle can use to give out a + * more accurate (or discount) asset rate. Though not verified or enforced + * by tapd, the suggested format for this field is a JSON string. + * This field is optional and can be left empty if no metadata is available. + * The maximum length of this field is 32'768 bytes. + */ + priceOracleMetadata: string; +} + +export interface AcceptedSellQuotes { + /** + * If swapping of assets is necessary to carry out the payment, a number of + * RFQ quotes may be negotiated for that purpose. The following field + * contains all the sell orders that were negotiated with our peers. + */ + acceptedSellOrders: PeerAcceptedSellQuote[]; } export interface SendPaymentResponse { @@ -143,17 +164,28 @@ export interface SendPaymentResponse { * 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. + * Deprecated. This will now only contain the first quote that was + * negotiated. Since the introduction of multi-rfq we now negotiate + * multiple quotes in the context of a payment. Use the new field named + * "accepted_sell_orders" to retrieve all of them. */ 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. + * If swapping of assets is necessary to carry out the payment, a number + * of RFQ quotes may be negotiated for that purpose. The following field + * contains all the sell orders that were negotiated with our peers. + */ + acceptedSellOrders: AcceptedSellQuotes | 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 { + /** The payment hash of the HODL invoice to be created. */ paymentHash: Uint8Array | string; } @@ -196,6 +228,17 @@ export interface AddInvoiceRequest { * settle this invoice. Mutually exclusive to asset_id. */ groupKey: Uint8Array | string; + /** + * An optional text field that can be used to provide additional metadata + * about the invoice to the price oracle. This can include information + * about the wallet end user that initiated the transaction, or any + * authentication information that the price oracle can use to give out a + * more accurate (or discount) asset rate. Though not verified or enforced + * by tapd, the suggested format for this field is a JSON string. + * This field is optional and can be left empty if no metadata is available. + * The maximum length of this field is 32'768 bytes. + */ + priceOracleMetadata: string; } export interface AddInvoiceResponse { @@ -221,6 +264,17 @@ export interface AssetPayReq { * Mutually exclusive to asset_id. */ groupKey: Uint8Array | string; + /** + * An optional text field that can be used to provide additional metadata + * about the invoice to the price oracle. This can include information + * about the wallet end user that initiated the transaction, or any + * authentication information that the price oracle can use to give out a + * more accurate (or discount) asset rate. Though not verified or enforced + * by tapd, the suggested format for this field is a JSON string. + * This field is optional and can be left empty if no metadata is available. + * The maximum length of this field is 32'768 bytes. + */ + priceOracleMetadata: string; } export interface AssetPayReqResponse { @@ -251,11 +305,14 @@ export interface TaprootAssetChannels { request?: DeepPartial ): Promise; /** + * Deprecated. * 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. + * + * @deprecated */ encodeCustomRecords( request?: DeepPartial diff --git a/lib/types/proto/tapd/tapcommon.ts b/lib/types/proto/tapd/tapcommon.ts new file mode 100644 index 0000000..ae2e847 --- /dev/null +++ b/lib/types/proto/tapd/tapcommon.ts @@ -0,0 +1,49 @@ +/* eslint-disable */ +/** Represents a Bitcoin transaction outpoint. */ +export interface OutPoint { + /** Raw bytes representing the transaction id. */ + txid: Uint8Array | string; + /** The index of the output on the transaction. */ + outputIndex: number; +} + +/** + * A transaction outpoint annotated with TAP-level asset metadata. It uniquely + * identifies an asset anchored at a specific outpoint. + */ +export interface AssetOutPoint { + /** + * The outpoint of the asset anchor, represented as a string in the + * format ":". The is the transaction ID of the UTXO, + * hex-encoded and byte-reversed (i.e., the internal little-endian + * 32-byte value is reversed to big-endian hex format) to match standard + * Bitcoin RPC and UI conventions. + */ + anchorOutPoint: string; + /** The asset ID of the asset anchored at the outpoint. */ + assetId: Uint8Array | string; + /** + * The script key of the asset. This is the taproot output key that the + * asset is locked to. + */ + scriptKey: Uint8Array | string; +} + +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 8b541f6..1c9346c 100644 --- a/lib/types/proto/tapd/taprootassets.ts +++ b/lib/types/proto/tapd/taprootassets.ts @@ -1,4 +1,5 @@ /* eslint-disable */ +import type { OutPoint } from './tapcommon'; export enum AssetType { /** @@ -91,14 +92,19 @@ export enum AddrVersion { * commitments. */ ADDR_VERSION_V1 = 'ADDR_VERSION_V1', + /** + * ADDR_VERSION_V2 - ADDR_VERSION_V2 is the address version that supports sending grouped + * assets and require the new auth mailbox proof courier address format. + */ + ADDR_VERSION_V2 = 'ADDR_VERSION_V2', UNRECOGNIZED = 'UNRECOGNIZED' } export enum ScriptKeyType { /** * SCRIPT_KEY_UNKNOWN - The type of script key is not known. This should only be stored for assets - * where we don't know the internal key of the script key (e.g. for - * imported proofs). + * where we don't know the internal key of the script key (e.g. for imported + * proofs). */ SCRIPT_KEY_UNKNOWN = 'SCRIPT_KEY_UNKNOWN', /** @@ -134,6 +140,16 @@ export enum ScriptKeyType { * selection. */ SCRIPT_KEY_CHANNEL = 'SCRIPT_KEY_CHANNEL', + /** + * SCRIPT_KEY_UNIQUE_PEDERSEN - The script key is derived using the asset ID and a single leaf that contains + * an un-spendable Pedersen commitment key + * `(OP_CHECKSIG )`. This can be used to create + * unique script keys for each virtual packet in the fragment, to avoid proof + * collisions in the universe, where the script keys should be spendable by + * a hardware wallet that only supports miniscript policies for signing P2TR + * outputs. + */ + SCRIPT_KEY_UNIQUE_PEDERSEN = 'SCRIPT_KEY_UNIQUE_PEDERSEN', UNRECOGNIZED = 'UNRECOGNIZED' } @@ -229,8 +245,23 @@ export interface AssetMeta { } export interface ListAssetRequest { + /** + * Whether to include each asset's witness in the response. The witness + * either contains the spending signatures or the split commitment witness, + * which can both be large and usually aren't very useful on the command + * line, so are omitted by default. + */ withWitness: boolean; + /** + * Include assets that are marked as spent (which is always true for burn + * or tombstone assets). + */ includeSpent: boolean; + /** + * Include assets that are leased (locked/reserved) by the daemon for a + * pending transfer. Leased assets cannot be used by the daemon until the + * pending transfer is confirmed or the lease expires. + */ includeLeased: boolean; /** * List assets that aren't confirmed yet. Only freshly minted assets will @@ -485,6 +516,11 @@ export interface Asset { assetGroup: AssetGroup | undefined; /** Describes where in the chain the asset is currently anchored. */ chainAnchor: AnchorInfo | undefined; + /** + * The asset's previous witnesses, which either contain the spending + * witness stack (usually a signature) or the split commitment witness + * (which is used to prove the split commitment of a split asset). + */ prevWitnesses: PrevWitness[]; /** Indicates whether the asset has been spent. */ isSpent: boolean; @@ -541,16 +577,34 @@ export interface Asset { } export interface PrevWitness { + /** The previous input asset that this witness is for. */ prevId: PrevInputAsset | undefined; + /** + * The witness stack that is used to prove the asset owner's authorization + * to spend an asset. This is only set if the asset is the root asset of an + * asset split. + */ txWitness: Uint8Array | string[]; + /** + * The split commitment that is used to prove the split commitment of a + * split asset. This is only set if the asset is a split asset. + */ splitCommitment: SplitCommitment | undefined; } export interface SplitCommitment { + /** + * The root asset that contains the transaction witness that authorizes the + * spend of the asset. + */ rootAsset: Asset | undefined; } export interface ListAssetResponse { + /** + * The list of assets found in the database matching the request query + * parameters. + */ assets: Asset[]; /** * This is a count of unconfirmed outgoing transfers. Unconfirmed transfers @@ -566,6 +620,11 @@ export interface ListAssetResponse { } export interface ListUtxosRequest { + /** + * Whether to include UTXOs that are marked as leased (locked/reserved) by + * the wallet for a pending transfer. Leased UTXOs cannot be used by the + * wallet until the pending transfer is confirmed or the lease expires. + */ includeLeased: boolean; /** * The script key type to filter the assets by. If not set, only assets with @@ -681,6 +740,8 @@ export interface AssetBalance { assetGenesis: GenesisInfo | undefined; /** The balance of the asset owned by the target daemon. */ balance: string; + /** The group key of the asset (if it belongs to a group). */ + groupKey: Uint8Array | string; } export interface AssetGroupBalance { @@ -691,8 +752,24 @@ export interface AssetGroupBalance { } export interface ListBalancesResponse { + /** + * The map of asset balances, where the key is the asset ID and the value + * is the balance of that asset owned by the target daemon. This is only + * set if group_by.asset_id is true in the request. + */ assetBalances: { [key: string]: AssetBalance }; + /** + * The map of asset group balances, where the key is the group key + * and the value is the balance of that group owned by the target daemon. + * This is only set if group_by.group_key is true in the request. + */ assetGroupBalances: { [key: string]: AssetGroupBalance }; + /** + * This is a count of unconfirmed outgoing transfers. Unconfirmed transfers + * (and the change resulting from them) do not appear in the balance. The + * balance only represents confirmed assets that are owned by the daemon. + */ + unconfirmedTransfers: string; } export interface ListBalancesResponse_AssetBalancesEntry { @@ -747,13 +824,23 @@ export interface ChainHash { } export interface AssetTransfer { + /** The timestamp of the transfer in UTC Unix time seconds. */ transferTimestamp: string; /** - * The new transaction that commits to the set of Taproot Assets found - * at the above new anchor point. + * The new transaction that commits to the set of Taproot Assets found at + * the above new anchor point. Note that this is in raw byte format, not + * the reversed hex string format that is used for displayed txids. When + * listing assets on the CLI we purposefully use the display format so it + * is easier to copy and paste into other tools. */ anchorTxHash: Uint8Array | string; + /** + * The height hint of the anchor transaction. This is the height at which + * the anchor transaction was published, so the actual inclusion height + * will be greater than this value. + */ anchorTxHeightHint: number; + /** The total fees paid by the anchor transaction in satoshis. */ anchorTxChainFees: string; /** Describes the set of spent assets. */ inputs: TransferInput[]; @@ -804,34 +891,113 @@ export interface TransferOutputAnchor { * chain. */ outpoint: string; + /** The anchor transaction output's value in satoshis. */ value: string; + /** + * The anchor transaction output's internal key, which is the Taproot + * internal key of the on-chain output. + */ internalKey: Uint8Array | string; + /** + * The Taproot Asset root commitment hash, which is the root of the + * Taproot Asset commitment tree for the asset that was created. + */ taprootAssetRoot: Uint8Array | string; + /** + * The Taproot merkle root hash committed to by the outpoint of this + * output. If there is no Tapscript sibling, this is equal to the Taproot + * Asset root commitment hash. + * If there is a Tapscript sibling, this is the tap branch root hash of the + * Taproot Asset root hash and the tapscript sibling. + */ merkleRoot: Uint8Array | string; + /** + * The serialized preimage of a Tapscript sibling, if there was one. If this + * is empty, then the merkle_root hash is equal to the Taproot root hash + * of the anchor output. + */ tapscriptSibling: Uint8Array | string; + /** + * The number of passive assets that were committed to this output. + * Passive assets are assets that are not actively spent, but are instead + * passively carried along with the main asset and re-anchored in the + * anchor output. + */ numPassiveAssets: number; - /** pk_script is the pkscript of the anchor output. */ + /** + * The actual output's script, which is the P2TR script for the final + * Taproot output key created by this transfer output. + */ pkScript: Uint8Array | string; } export interface TransferOutput { + /** + * The transfer output's on-chain anchor information, which contains the + * BTC-level output information that anchors the Taproot Asset commitment + * for this output. + */ anchor: TransferOutputAnchor | undefined; + /** The script key of the asset that was created. */ scriptKey: Uint8Array | string; + /** + * Indicates whether the script key is known to the wallet of the lnd node + * connected to the Taproot Asset daemon. If true, the asset will be shown + * in the wallet balance. + */ scriptKeyIsLocal: boolean; + /** The amount of the asset that was created in this output. */ amount: string; /** * The new individual transition proof (not a full proof file) that proves * the inclusion of the new asset within the new AnchorTx. */ newProofBlob: Uint8Array | string; + /** + * The split commitment root hash of the asset that was created in this + * output. This is only set if the asset is a split root output, meaning + * that the asset is a split root output that carries the change from a + * split or a tombstone from a non-interactive full value send output. + */ splitCommitRootHash: Uint8Array | string; + /** + * The type of the output. This is used to distinguish between a simple + * output that is not a split root and does not carry passive assets, and a + * split root output that carries the change from a split or a tombstone + * from a non-interactive full value send output. + */ outputType: OutputType; + /** + * The asset version of the output. This is used to determine how the asset + * is encoded in the Taproot Asset commitment tree. + */ assetVersion: AssetVersion; + /** + * The lock time of the output, which is an optional field that can be set + * to delay the spending of the output until a certain time in the future. + */ lockTime: string; + /** + * The relative lock time of the output, which is an optional field that + * can be set to delay the spending of the output relative to the block + * height at which the output is confirmed. + */ relativeLockTime: string; /** The delivery status of the proof associated with this output. */ proofDeliveryStatus: ProofDeliveryStatus; + /** The asset ID of the asset that was created in this output. */ assetId: Uint8Array | string; + /** + * The proof courier address that was used to deliver the proof for this + * output. + */ + proofCourierAddr: string; + /** + * The Taproot Asset address that was used to create the output. This is + * only set for new outputs for tapd versions that support the address V2 + * format. For older versions, this field will be empty. + */ + tapAddr: string; } export interface StopRequest {} @@ -841,23 +1007,47 @@ export interface StopResponse {} export interface DebugLevelRequest { /** If true, all the valid debug sub-systems will be returned. */ show: boolean; + /** + * If set, the debug level for the sub-system will be set to this value. + * Can be one of: "trace", "debug", "info", "warn", "error", "critical", + * "off", to set a global level, optionally followed by a comma-separated + * list of sub-systems to set the level for. For example: + * "debug,TADB=info,UNIV=warn". + */ levelSpec: string; } export interface DebugLevelResponse { + /** + * The list of available logging sub-systems that can be set to a specific + * debug level. + */ subSystems: string; } export interface Addr { /** The bech32 encoded Taproot Asset address. */ encoded: string; - /** The asset ID that uniquely identifies the asset. */ + /** + * The asset ID that uniquely identifies the asset. This can be all zeroes + * for V2 addresses that have a group key set. + */ assetId: Uint8Array | string; /** The type of the asset. */ assetType: AssetType; - /** The total amount of the asset stored in this Taproot Asset UTXO. */ + /** + * The total amount of the asset stored in this Taproot Asset UTXO. The + * amount is allowed to be unset for V2 addresses, where the sender will + * post a fragment containing the asset IDs and amounts to the proof + * courier's auth mailbox. + */ amount: string; - /** The group key of the asset (if it exists) */ + /** + * The group key of the asset group to receive assets for. If this field + * is set, then any asset of the group can be sent to this address. Can only + * be specified for V2 addresses. If this field is set, the asset_id + * field must be empty. + */ groupKey: Uint8Array | string; /** * The specific script key the asset must commit to in order to transfer @@ -879,7 +1069,11 @@ export interface Addr { * transfer assets described in this address. */ taprootOutputKey: Uint8Array | string; - /** The address of the proof courier service used in proof transfer. */ + /** + * The address of the proof courier service used in proof transfer. For V2 + * addresses the proof courier address is mandatory and must be a valid auth + * mailbox address (authmailbox+universerpc://host:port). + */ proofCourierAddr: string; /** The asset version of the address. */ assetVersion: AssetVersion; @@ -905,11 +1099,22 @@ export interface QueryAddrRequest { } export interface QueryAddrResponse { + /** The list of addresses that match the query parameters. */ addrs: Addr[]; } export interface NewAddrRequest { + /** + * The asset ID to create the address for. This is required for V0 and V1 + * addresses. For V2 addresses, this field is optional and must be empty if the + * group key is set. + */ assetId: Uint8Array | string; + /** + * The number of asset units to be sent to the address. This is required for V0 + * and V1 addresses. For V2 addresses, this field is optional and can be left + * at 0 to indicate that the sender can choose the amount of assets to send. + */ amt: string; /** * The optional script key that the receiving asset should be locked to. If no @@ -945,6 +1150,17 @@ export interface NewAddrRequest { assetVersion: AssetVersion; /** The version of this address. */ addressVersion: AddrVersion; + /** + * The group key to receive assets for. This can only be specified for V2 + * addresses. If this field is set, the asset_id field must be empty. + */ + groupKey: Uint8Array | string; + /** + * If set, the daemon skips the connectivity check to the proof courier service + * when creating an address. Connection checks currently apply only to certain + * address schemes. Use this to create addresses while offline. + */ + skipProofCourierConnCheck: boolean; } export interface ScriptKeyTypeQuery { @@ -1009,6 +1225,7 @@ export interface TapBranch { } export interface DecodeAddrRequest { + /** The bech32 encoded Taproot Asset address to decode. */ addr: string; } @@ -1018,6 +1235,10 @@ export interface ProofFile { * individual mint/transfer proof. */ rawProofFile: Uint8Array | string; + /** + * The genesis point of the proof file, which is the asset's genesis + * transaction outpoint. + */ genesisPoint: string; } @@ -1095,6 +1316,7 @@ export interface DecodedProof { } export interface VerifyProofResponse { + /** Whether the proof file was valid or not. */ valid: boolean; /** The decoded last proof in the file if the proof file was valid. */ decodedProof: DecodedProof | undefined; @@ -1121,12 +1343,16 @@ export interface DecodeProofRequest { } export interface DecodeProofResponse { + /** The decoded, more human-readable proof. */ decodedProof: DecodedProof | undefined; } export interface ExportProofRequest { + /** The asset ID of the asset to export the proof for. */ assetId: Uint8Array | string; + /** The script key of the asset to export the proof for. */ scriptKey: Uint8Array | string; + /** The on-chain outpoint of the asset to export the proof for. */ outpoint: OutPoint | undefined; } @@ -1181,6 +1407,16 @@ export interface AddrReceivesRequest { filterAddr: string; /** Filter receives by a specific status. Leave empty to get all receives. */ filterStatus: AddrEventStatus; + /** + * Filter receives by creation time greater than or equal to this timestamp. + * If not set, no start time filtering is applied. + */ + startTimestamp: string; + /** + * Filter receives by creation time less than or equal to this timestamp. + * If not set, no end time filtering is applied. + */ + endTimestamp: string; } export interface AddrReceivesResponse { @@ -1189,6 +1425,15 @@ export interface AddrReceivesResponse { } export interface SendAssetRequest { + /** + * The list of TAP addresses to send assets to. The amount to send to each + * address is determined by the amount specified in the address itself. For + * V2 addresses that are allowed to not specify an amount, use the + * addresses_with_amounts list to specify the amount to send to each + * address. The tap_addrs and addresses_with_amounts lists are mutually + * exclusive, meaning that if addresses_with_amounts is set, then tap_addrs + * must be empty, and vice versa. + */ tapAddrs: string[]; /** The optional fee rate to use for the minting transaction, in sat/kw. */ feeRate: number; @@ -1204,29 +1449,79 @@ export interface SendAssetRequest { * is not immediately available. */ skipProofCourierPingCheck: boolean; + /** + * A list of addresses and the amounts of asset units to send to them. This + * must be used for V2 TAP addresses that don't specify an amount in the + * address itself and allow the sender to choose the amount to send. The + * tap_addrs and addresses_with_amounts lists are mutually exclusive, + * meaning that if addresses_with_amounts is set, then tap_addrs must be + * empty, and vice versa. + */ + addressesWithAmounts: AddressWithAmount[]; +} + +export interface AddressWithAmount { + /** The TAP address to send assets to. */ + tapAddr: string; + /** + * The amount of asset units to send to the address. This is only used for + * re-usable V2 addresses that don't specify an amount in the address itself + * and allow the sender to specify the amount on each send attempt. For V0 + * or V1 addresses, this can be left empty (zero) as the amount is taken + * from the address itself. + */ + amount: string; } export interface PrevInputAsset { + /** + * The previous input's anchor point, which is the on-chain outpoint the + * asset was anchored to. + */ anchorPoint: string; + /** The asset ID of the asset that was spent as an input. */ assetId: Uint8Array | string; + /** The script key of the asset that was spent as an input. */ scriptKey: Uint8Array | string; + /** The amount of the asset that was spent as an input. */ amount: string; } export interface SendAssetResponse { + /** The transfer that was created to send assets to one or more addresses. */ transfer: AssetTransfer | undefined; } export interface GetInfoRequest {} export interface GetInfoResponse { + /** The full version string of the Taproot Asset daemon. */ version: string; + /** The full version string of the LND node that this daemon is connected to. */ lndVersion: string; + /** + * The network this daemon is connected to, e.g. "mainnet", "testnet", or + * any other supported network. + */ network: string; + /** The public key of the LND node that this daemon is connected to. */ lndIdentityPubkey: string; + /** The alias of the LND node that this daemon is connected to. */ nodeAlias: string; + /** + * The current block height as seen by the LND node this daemon is + * connected to. + */ blockHeight: number; + /** + * The current block hash as seen by the LND node this daemon is connected + * to. + */ blockHash: string; + /** + * Whether the LND node this daemon is connected to is synced to the + * Bitcoin chain. + */ syncToChain: boolean; } @@ -1241,11 +1536,58 @@ export interface FetchAssetMetaRequest { metaHashStr: string | undefined; } +export interface FetchAssetMetaResponse { + /** + * The raw data of the asset meta data. Based on the type below, this may be + * structured data such as a text file or PDF. The size of the data is limited + * to 1MiB. + */ + data: Uint8Array | string; + /** The type of the asset meta data. */ + type: AssetMetaType; + /** + * The hash of the meta. This is the hash of the TLV serialization of the meta + * itself. + */ + metaHash: Uint8Array | string; + /** + * A map of unknown odd TLV types that were encountered during asset meta data + * decoding. + */ + unknownOddTypes: { [key: string]: Uint8Array | string }; + /** + * The decimal display value of the asset. This is used to determine the number + * of decimal places to display when presenting the asset amount to the user. + */ + decimalDisplay: number; + /** + * Boolean flag indicating whether the asset-group issuer publishes + * universe-supply commitments to the canonical universe set. + */ + universeCommitments: boolean; + /** + * List of canonical universe URLs where the asset-group issuer publishes + * asset-related proofs. + */ + canonicalUniverseUrls: string[]; + /** + * The public key that is used to verify universe supply commitment related + * on-chain outputs and proofs. + */ + delegationKey: Uint8Array | string; +} + +export interface FetchAssetMetaResponse_UnknownOddTypesEntry { + key: string; + value: Uint8Array | string; +} + export interface BurnAssetRequest { /** The asset ID of the asset to burn units of. */ assetId: Uint8Array | string | undefined; /** The hex encoded asset ID of the asset to burn units of. */ assetIdStr: string | undefined; + /** The number of asset units to burn. This must be greater than zero. */ amountToBurn: string; /** * A safety check to ensure the user is aware of the destructive nature of @@ -1287,16 +1629,10 @@ export interface AssetBurn { } export interface ListBurnsResponse { + /** The list of asset burns that match the query parameters. */ burns: AssetBurn[]; } -export interface OutPoint { - /** Raw bytes representing the transaction id. */ - txid: Uint8Array | string; - /** The index of the output on the transaction. */ - outputIndex: number; -} - export interface SubscribeReceiveEventsRequest { /** * Filter receives by a specific address. Leave empty to get all receive @@ -1343,6 +1679,11 @@ export interface SubscribeSendEventsRequest { * transfer label. */ filterLabel: 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 SendEvent { @@ -1389,6 +1730,10 @@ export interface SendEvent { } export interface AnchorTransaction { + /** + * The on-chain anchor transaction PSBT packet that was created by the + * daemon. + */ anchorPsbt: Uint8Array | string; /** The index of the (added) change output or -1 if no change was left over. */ changeOutputIndex: number; @@ -1421,6 +1766,7 @@ export interface RegisterTransferRequest { } export interface RegisterTransferResponse { + /** The asset transfer that was registered. */ registeredAsset: Asset | undefined; } @@ -1575,7 +1921,7 @@ export interface TaprootAssets { */ fetchAssetMeta( request?: DeepPartial - ): Promise; + ): Promise; /** * tapcli: `events receive` * SubscribeReceiveEvents allows a caller to subscribe to receive events for diff --git a/lib/types/proto/tapd/universerpc/universe.ts b/lib/types/proto/tapd/universerpc/universe.ts index e0a9a59..596f3b4 100644 --- a/lib/types/proto/tapd/universerpc/universe.ts +++ b/lib/types/proto/tapd/universerpc/universe.ts @@ -6,6 +6,7 @@ import type { GenesisReveal, GroupKeyReveal } from '../taprootassets'; +import type { AssetOutPoint, OutPoint } from '../tapcommon'; export enum ProofType { PROOF_TYPE_UNSPECIFIED = 'PROOF_TYPE_UNSPECIFIED', @@ -111,6 +112,7 @@ export interface ID { } export interface UniverseRoot { + /** The ID of the asset universe root. */ id: ID | undefined; /** * The merkle sum sparse merkle tree root associated with the above @@ -296,6 +298,7 @@ export interface InfoResponse { } export interface SyncTarget { + /** The ID of the asset to sync. */ id: ID | undefined; } @@ -331,23 +334,37 @@ export interface SyncResponse { } export interface UniverseFederationServer { + /** + * The host of the federation server, which is used to connect to the + * server to push proofs and sync new proofs. + */ host: string; + /** + * The numeric ID of the federation server. This is used to identify + * existing servers when adding or deleting them from the federation. + */ id: number; } export interface ListFederationServersRequest {} export interface ListFederationServersResponse { + /** + * The list of federation servers that make up the local Universe + * federation. + */ servers: UniverseFederationServer[]; } export interface AddFederationServerRequest { + /** The federation server to add to the local Universe federation. */ servers: UniverseFederationServer[]; } export interface AddFederationServerResponse {} export interface DeleteFederationServerRequest { + /** The federation server to delete from the local Universe federation. */ servers: UniverseFederationServer[]; } @@ -361,12 +378,31 @@ export interface StatsResponse { } export interface AssetStatsQuery { + /** The asset name filter. If this is empty, then all assets are returned. */ assetNameFilter: string; + /** The asset ID filter. If this is empty, then all assets are returned. */ assetIdFilter: Uint8Array | string; + /** + * The asset type filter. If this is set to FILTER_ASSET_NONE, then all + * assets are returned. If set to FILTER_ASSET_NORMAL, then only normal + * assets are returned. If set to FILTER_ASSET_COLLECTIBLE, then only + * collectible assets are returned. + */ assetTypeFilter: AssetTypeFilter; + /** + * The sort order for the query. If this is set to SORT_BY_NONE, then the + * results are not sorted. + */ sortBy: AssetQuerySort; + /** The offset for the page. This is used for pagination. */ offset: number; + /** The length limit for the page. This is used for pagination. */ limit: number; + /** + * The direction of the sort. If this is set to SORT_DIRECTION_ASC, then + * the results are sorted in ascending order. If set to + * SORT_DIRECTION_DESC, then the results are sorted in descending order. + */ direction: SortDirection; } @@ -404,39 +440,78 @@ export interface AssetStatsSnapshot { } export interface AssetStatsAsset { + /** The ID of the asset. */ assetId: Uint8Array | string; + /** + * The asset's genesis point, which is the outpoint of the genesis + * transaction that created the asset. This is a hex encoded string. + */ genesisPoint: string; + /** + * The total supply of the asset. This is the total number of units of the + * asset that have been issued. + */ totalSupply: string; + /** The human-readable name of the asset. */ assetName: string; + /** + * The type of the asset. This can be either a normal asset or a collectible + * asset. + */ assetType: AssetType; + /** The height of the block at which the asset was created. */ genesisHeight: number; + /** + * The timestamp of the block at which the asset was created, in Unix epoch + * time (seconds). + */ genesisTimestamp: string; + /** + * The anchor point of the asset, which is a human-readable string that + * represents the asset's anchor point in the blockchain. + */ anchorPoint: string; + /** + * The decimal display value for the asset. This is the number of decimal + * places that the asset can be divided into. + */ decimalDisplay: number; } export interface UniverseAssetStats { + /** The asset statistics snapshot for the queried assets. */ assetStats: AssetStatsSnapshot[]; } export interface QueryEventsRequest { + /** The start timestamp for the query, in Unix epoch time (seconds). */ startTimestamp: string; + /** The end timestamp for the query, in Unix epoch time (seconds). */ endTimestamp: string; } export interface QueryEventsResponse { + /** + * The list of grouped universe events that occurred within the specified + * time range. Each entry in the list represents a day, with the number of + * sync and new proof events that occurred on that day. + */ events: GroupedUniverseEvents[]; } export interface GroupedUniverseEvents { /** The date the events occurred on, formatted as YYYY-MM-DD. */ date: string; + /** The number of sync events that occurred on this date. */ syncEvents: string; + /** The number of new proof events that occurred on this date. */ newProofEvents: string; } export interface SetFederationSyncConfigRequest { + /** The global federation sync configs for the given proof types. */ globalSyncConfigs: GlobalFederationSyncConfig[]; + /** The asset federation sync configs for the given universe IDs. */ assetSyncConfigs: AssetFederationSyncConfig[]; } @@ -490,10 +565,326 @@ export interface QueryFederationSyncConfigRequest { } export interface QueryFederationSyncConfigResponse { + /** The global federation sync configs for the given proof types. */ globalSyncConfigs: GlobalFederationSyncConfig[]; + /** The asset federation sync configs for the given universe IDs. */ assetSyncConfigs: AssetFederationSyncConfig[]; } +export interface IgnoreAssetOutPointRequest { + /** The outpoint of the asset to ignore. */ + assetOutPoint: AssetOutPoint | undefined; + /** The amount of asset units at the associated asset outpoint. */ + amount: string; +} + +export interface IgnoreAssetOutPointResponse { + /** + * The key identifying the signed ignore outpoint leaf in the ignore supply + * commitment subtree. + */ + leafKey: Uint8Array | string; + /** The signed ignore outpoint leaf in the ignore supply commitment tree. */ + leaf: MerkleSumNode | undefined; +} + +export interface UpdateSupplyCommitRequest { + /** The 32-byte asset group key specified as raw bytes (gRPC only). */ + groupKeyBytes: Uint8Array | string | undefined; + /** + * The 32-byte asset group key encoded as hex string (use this for + * REST). + */ + groupKeyStr: string | undefined; +} + +export interface UpdateSupplyCommitResponse {} + +export interface FetchSupplyCommitRequest { + /** The 32-byte asset group key specified as raw bytes (gRPC only). */ + groupKeyBytes: Uint8Array | string | undefined; + /** + * The 32-byte asset group key encoded as hex string (use this for + * REST). + */ + groupKeyStr: string | undefined; + /** + * Fetch the the supply commitment that created this new commitment + * output on chain. + */ + commitOutpoint: OutPoint | undefined; + /** + * Fetch the supply commitment that spent the specified commitment + * output on chain to create a new supply commitment. This can be used + * to traverse the chain of supply commitments by watching the spend of + * the commitment output. + */ + spentCommitOutpoint: OutPoint | undefined; + /** + * Fetch the very first supply commitment for the asset group. This + * returns the initial supply commitment that spent the pre-commitment + * output of the very first asset mint of a grouped asset (also known + * as the group anchor). This is useful as the starting point to fetch + * all supply commitments for a grouped asset one by one. + */ + veryFirst: boolean | undefined; + /** + * Fetch the latest supply commitment for the asset group. This returns + * the most recent supply commitment that is anchored on chain for the + * asset group. This is useful to always get the current supply state + * of the asset group. + */ + latest: boolean | undefined; +} + +export interface SupplyCommitSubtreeRoot { + /** The type of the supply commit subtree. */ + type: string; + /** The root node of the supply commit subtree. */ + rootNode: MerkleSumNode | undefined; + /** + * The leaf key which locates the subtree leaf node in the supply commit + * tree. + */ + supplyTreeLeafKey: Uint8Array | string; + /** The inclusion proof for the supply commit subtree root node. */ + supplyTreeInclusionProof: Uint8Array | string; +} + +export interface FetchSupplyCommitResponse { + /** + * The supply commitment chain data that contains both the commitment and + * chain proof information. + */ + chainData: SupplyCommitChainData | undefined; + /** + * The total number of satoshis in on-chain fees paid by the supply + * commitment transaction. + */ + txChainFeesSats: string; + /** The root of the issuance tree for the specified asset. */ + issuanceSubtreeRoot: SupplyCommitSubtreeRoot | undefined; + /** The root of the burn tree for the specified asset. */ + burnSubtreeRoot: SupplyCommitSubtreeRoot | undefined; + /** The root of the ignore tree for the specified asset. */ + ignoreSubtreeRoot: SupplyCommitSubtreeRoot | undefined; + /** + * The issuance leaves that were added by this supply commitment. Does not + * include leaves that were already present in the issuance subtree before + * the block height at which this supply commitment was anchored. + */ + issuanceLeaves: SupplyLeafEntry[]; + /** + * The burn leaves that were added by this supply commitment. Does not + * include leaves that were already present in the burn subtree before + * the block height at which this supply commitment was anchored. + */ + burnLeaves: SupplyLeafEntry[]; + /** + * The ignore leaves that were added by this supply commitment. Does not + * include leaves that were already present in the ignore subtree before + * the block height at which this supply commitment was anchored. + */ + ignoreLeaves: SupplyLeafEntry[]; + /** + * The total outstanding supply of the asset after applying all the supply + * changes (issuance, burn, ignore) included in this supply commitment. + */ + totalOutstandingSupply: string; + /** + * The outpoint of the previous commitment that this new commitment is + * spending. This must be set unless this is the very first supply + * commitment of a grouped asset. + */ + spentCommitmentOutpoint: OutPoint | undefined; + /** + * A map of block height to supply leaf block header for all block heights + * referenced in supply leaves. + */ + blockHeaders: { [key: number]: SupplyLeafBlockHeader }; +} + +export interface FetchSupplyCommitResponse_BlockHeadersEntry { + key: number; + value: SupplyLeafBlockHeader | undefined; +} + +export interface FetchSupplyLeavesRequest { + /** The 32-byte asset group key specified as raw bytes (gRPC only). */ + groupKeyBytes: Uint8Array | string | undefined; + /** + * The 32-byte asset group key encoded as hex string (use this for + * REST). + */ + groupKeyStr: string | undefined; + /** The start block height for the range of supply leaves to fetch. */ + blockHeightStart: number; + /** The end block height for the range of supply leaves to fetch. */ + blockHeightEnd: number; + /** + * Optional: A list of issuance leaf keys. For each key in this list, + * the endpoint will generate and return an inclusion proof. + */ + issuanceLeafKeys: Uint8Array | string[]; + /** + * Optional: A list of burn leaf keys. For each key in this list, + * the endpoint will generate and return an inclusion proof. + */ + burnLeafKeys: Uint8Array | string[]; + /** + * Optional: A list of ignore leaf keys. For each key in this list, the + * endpoint will generate and return an inclusion proof. + */ + ignoreLeafKeys: Uint8Array | string[]; +} + +/** + * SupplyLeafKey identifies a supply leaf entry. It contains the components + * used to derive the key, which is computed as a hash of these fields. + */ +export interface SupplyLeafKey { + /** The outpoint associated with the supply leaf. */ + outpoint: Outpoint | undefined; + /** + * The script key of the supply leaf. This is the script key of the asset + * point. + */ + scriptKey: Uint8Array | string; + /** + * The asset ID associated with the supply leaf. This is only set for + * ignore type supply leaves. + */ + assetId: Uint8Array | string; +} + +export interface SupplyLeafEntry { + /** The key that identifies the supply leaf in the supply commitment subtree. */ + leafKey: SupplyLeafKey | undefined; + /** + * The merkle sum node representing the supply leaf in the supply commitment + * subtree. + */ + leafNode: MerkleSumNode | undefined; + /** The block height at which the supply leaf was created. */ + blockHeight: number; + /** The raw serialized bytes of the supply leaf. */ + rawLeaf: Uint8Array | string; +} + +export interface SupplyLeafBlockHeader { + /** Block header timestamp in seconds since unix epoch. */ + timestamp: string; + /** 32-byte block header hash. */ + hash: Uint8Array | string; +} + +export interface FetchSupplyLeavesResponse { + issuanceLeaves: SupplyLeafEntry[]; + burnLeaves: SupplyLeafEntry[]; + ignoreLeaves: SupplyLeafEntry[]; + /** + * Inclusion proofs for each issuance leaf key provided in the request. + * Each entry corresponds to the key at the same index in + * `issuance_leaf_keys`. + */ + issuanceLeafInclusionProofs: Uint8Array | string[]; + /** + * Inclusion proofs for each burn leaf key provided in the request. + * Each entry corresponds to the key at the same index in `burn_leaf_keys`. + */ + burnLeafInclusionProofs: Uint8Array | string[]; + /** + * Inclusion proofs for each ignored leaf key provided in the request. + * Each entry corresponds to the key at the same index in + * `ignore_leaf_keys`. + */ + ignoreLeafInclusionProofs: Uint8Array | string[]; + /** + * A map of block height to supply leaf block header for all block heights + * referenced in supply leaves. + */ + blockHeaders: { [key: number]: SupplyLeafBlockHeader }; +} + +export interface FetchSupplyLeavesResponse_BlockHeadersEntry { + key: number; + value: SupplyLeafBlockHeader | undefined; +} + +/** + * SupplyCommitChainData represents the on-chain artifacts for a supply + * commitment update. + */ +export interface SupplyCommitChainData { + /** The raw transaction that created the root commitment. */ + txn: Uint8Array | string; + /** The index of the output in the transaction where the commitment resides. */ + txOutIdx: number; + /** The internal key used to create the commitment output. */ + internalKey: Uint8Array | string; + /** The taproot output key used to create the commitment output. */ + outputKey: Uint8Array | string; + /** + * The root hash of the supply tree that contains the set of + * sub-commitments. The sum value of this tree is the outstanding supply + * value. + */ + supplyRootHash: Uint8Array | string; + /** + * The sum value of the supply root tree, representing the outstanding + * supply amount. + */ + supplyRootSum: string; + /** + * The block header of the block that contains the supply commitment + * transaction. + */ + blockHeader: Uint8Array | string; + /** The hash of the block that contains the commitment. */ + blockHash: Uint8Array | string; + /** + * The block height of the block that contains the supply commitment + * transaction. + */ + blockHeight: number; + /** + * The merkle proof that proves that the supply commitment transaction is + * included in the block. + */ + txBlockMerkleProof: Uint8Array | string; + /** The index of the supply commitment transaction in the block. */ + txIndex: number; + /** The outpoint in the transaction where the commitment resides. */ + commitOutpoint: string; +} + +export interface InsertSupplyCommitRequest { + /** The 32-byte asset group key specified as raw bytes (gRPC only). */ + groupKeyBytes: Uint8Array | string | undefined; + /** + * The 32-byte asset group key encoded as hex string (use this for + * REST). + */ + groupKeyStr: string | undefined; + /** + * The supply commitment chain data that contains both the commitment and + * chain proof information. + */ + chainData: SupplyCommitChainData | undefined; + /** + * The outpoint of the previous commitment that this new commitment is + * spending. This must be set unless this is the very first supply + * commitment of a grouped asset. + */ + spentCommitmentOutpoint: OutPoint | undefined; + /** The supply leaves that represent the supply changes for the asset group. */ + issuanceLeaves: SupplyLeafEntry[]; + burnLeaves: SupplyLeafEntry[]; + ignoreLeaves: SupplyLeafEntry[]; +} + +export interface InsertSupplyCommitResponse {} + export interface Universe { /** * tapcli: `universe multiverse` @@ -578,7 +969,9 @@ export interface Universe { ): Promise; /** * tapcli: `universe info` - * Info returns a set of information about the current state of the Universe. + * Info returns a set of information about the current state of the Universe + * and allows a caller to check that a universe server is reachable and + * configured correctly to allow proof courier access without macaroons. */ info(request?: DeepPartial): Promise; /** @@ -656,6 +1049,49 @@ export interface Universe { queryFederationSyncConfig( request?: DeepPartial ): Promise; + /** + * tapcli: `universe ignoreoutpoint` + * IgnoreAssetOutPoint allows an asset issuer to mark a specific asset outpoint + * as ignored. An ignored outpoint will be included in the next universe supply + * commitment transaction that is published. + */ + ignoreAssetOutPoint( + request?: DeepPartial + ): Promise; + /** + * tapcli: `universe updatesupplycommit` + * UpdateSupplyCommit updates the on-chain supply commitment for a specific + * asset group. + */ + updateSupplyCommit( + request?: DeepPartial + ): Promise; + /** + * tapcli: `universe fetchsupplycommit` + * FetchSupplyCommit fetches the on-chain supply commitment for a specific + * asset group. + */ + fetchSupplyCommit( + request?: DeepPartial + ): Promise; + /** + * tapcli: `universe supplyleaves` + * FetchSupplyLeaves fetches the supply leaves for a specific asset group + * within a specified block height range. The leaves include issuance, burn, + * and ignore leaves, which represent the supply changes for the asset group. + */ + fetchSupplyLeaves( + request?: DeepPartial + ): Promise; + /** + * tapcli: `universe supplycommit insert` + * InsertSupplyCommit inserts a supply commitment for a specific asset + * group. This includes the commitment details, supply leaves (issuance, burn, + * and ignore), and chain proof that proves the commitment has been mined. + */ + insertSupplyCommit( + request?: DeepPartial + ): Promise; } type Builtin = diff --git a/package.json b/package.json index 9f0693d..87a3336 100644 --- a/package.json +++ b/package.json @@ -1,16 +1,16 @@ { "name": "@lightninglabs/lnc-core", - "version": "0.3.4-alpha", + "version": "0.3.5-alpha", "description": "Type definitions and utilities for Lightning Node Connect", "main": "./dist/index.js", "types": "./dist/index.d.ts", "config": { - "lnd_release_tag": "v0.19.1-beta", - "loop_release_tag": "v0.31.2-beta", - "pool_release_tag": "v0.6.6-beta", - "faraday_release_tag": "v0.2.16-alpha", - "tapd_release_tag": "v0.6.0", - "lit_release_tag": "v0.15.0-alpha", + "lnd_release_tag": "v0.20.0-beta", + "loop_release_tag": "v0.31.7-beta", + "pool_release_tag": "v0.6.4-beta", + "faraday_release_tag": "v0.2.14-alpha", + "tapd_release_tag": "v0.7.0", + "lit_release_tag": "v0.16.0-alpha", "protoc_version": "21.9" }, "scripts": { diff --git a/protos/faraday/v0.2.16-alpha/faraday.proto b/protos/faraday/v0.2.14-alpha/faraday.proto similarity index 100% rename from protos/faraday/v0.2.16-alpha/faraday.proto rename to protos/faraday/v0.2.14-alpha/faraday.proto diff --git a/protos/lit/v0.15.0-alpha/firewall.proto b/protos/lit/v0.16.0-alpha/firewall.proto similarity index 100% rename from protos/lit/v0.15.0-alpha/firewall.proto rename to protos/lit/v0.16.0-alpha/firewall.proto diff --git a/protos/lit/v0.15.0-alpha/lit-autopilot.proto b/protos/lit/v0.16.0-alpha/lit-autopilot.proto similarity index 100% rename from protos/lit/v0.15.0-alpha/lit-autopilot.proto rename to protos/lit/v0.16.0-alpha/lit-autopilot.proto diff --git a/protos/lit/v0.15.0-alpha/lit-sessions.proto b/protos/lit/v0.16.0-alpha/lit-sessions.proto similarity index 100% rename from protos/lit/v0.15.0-alpha/lit-sessions.proto rename to protos/lit/v0.16.0-alpha/lit-sessions.proto diff --git a/protos/lit/v0.15.0-alpha/lit-status.proto b/protos/lit/v0.16.0-alpha/lit-status.proto similarity index 100% rename from protos/lit/v0.15.0-alpha/lit-status.proto rename to protos/lit/v0.16.0-alpha/lit-status.proto diff --git a/protos/lnd/v0.19.1-beta/autopilotrpc/autopilot.proto b/protos/lnd/v0.20.0-beta/autopilotrpc/autopilot.proto similarity index 100% rename from protos/lnd/v0.19.1-beta/autopilotrpc/autopilot.proto rename to protos/lnd/v0.20.0-beta/autopilotrpc/autopilot.proto diff --git a/protos/lnd/v0.19.1-beta/chainrpc/chainnotifier.proto b/protos/lnd/v0.20.0-beta/chainrpc/chainnotifier.proto similarity index 100% rename from protos/lnd/v0.19.1-beta/chainrpc/chainnotifier.proto rename to protos/lnd/v0.20.0-beta/chainrpc/chainnotifier.proto diff --git a/protos/lnd/v0.19.1-beta/invoicesrpc/invoices.proto b/protos/lnd/v0.20.0-beta/invoicesrpc/invoices.proto similarity index 100% rename from protos/lnd/v0.19.1-beta/invoicesrpc/invoices.proto rename to protos/lnd/v0.20.0-beta/invoicesrpc/invoices.proto diff --git a/protos/lnd/v0.19.1-beta/lightning.proto b/protos/lnd/v0.20.0-beta/lightning.proto similarity index 96% rename from protos/lnd/v0.19.1-beta/lightning.proto rename to protos/lnd/v0.20.0-beta/lightning.proto index 5ee8e67..9c9abdd 100644 --- a/protos/lnd/v0.19.1-beta/lightning.proto +++ b/protos/lnd/v0.20.0-beta/lightning.proto @@ -341,6 +341,13 @@ service Lightning { */ rpc SubscribeInvoices (InvoiceSubscription) returns (stream Invoice); + /* lncli: `deletecanceledinvoice` + DeleteCanceledInvoice removes a canceled invoice from the database. If the + invoice is not in the canceled state, an error will be returned. + */ + rpc DeleteCanceledInvoice (DelCanceledInvoiceReq) + returns (DelCanceledInvoiceResp); + /* lncli: `decodepayreq` DecodePayReq takes an encoded payment request string and attempts to decode it, returning a full description of the conditions encoded within the @@ -548,9 +555,10 @@ service Lightning { returns (ListPermissionsResponse); /* - CheckMacaroonPermissions checks whether a request follows the constraints - imposed on the macaroon and that the macaroon is authorized to follow the - provided permissions. + CheckMacaroonPermissions checks whether the provided macaroon contains all + the provided permissions. If the macaroon is valid (e.g. all caveats are + satisfied), and all permissions provided in the request are met, then + this RPC returns true. */ rpc CheckMacaroonPermissions (CheckMacPermRequest) returns (CheckMacPermResponse); @@ -1911,6 +1919,7 @@ message Peer { repeated TimestampedError errors = 12; /* + This field is populated when the peer has at least one channel with us. 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 @@ -1919,6 +1928,7 @@ message Peer { int32 flap_count = 13; /* + This field is populated when the peer has at least one channel with us. 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. */ @@ -2074,13 +2084,6 @@ message Chain { string network = 2; } -message ConfirmationUpdate { - bytes block_sha = 1; - int32 block_height = 2; - - uint32 num_confs_left = 3; -} - message ChannelOpenUpdate { ChannelPoint channel_point = 1; } @@ -2847,6 +2850,25 @@ message PendingChannelsResponse { // very likely canceled the funding and the channel will never become // fully operational. int32 funding_expiry_blocks = 3; + + // The number of blocks remaining until the channel status changes from + // pending to active. A value of 0 indicates that the channel is now + // active. + // + // "Active" here means both channel peers have the channel marked OPEN + // and can immediately start using it. For public channels, this does + // not imply a channel_announcement has been gossiped. It only becomes + // public on the network after 6 on‐chain confirmations. + // See BOLT07 "Routing Gossip": + // https://github.com/lightning/bolts/blob/master/07-routing-gossip.md + // + // ZeroConf channels bypass the pending state entirely: they are marked + // active immediately upon creation, so they never show up as "pending". + uint32 confirmations_until_active = 7; + + // The confirmation height records the block height at which the funding + // transaction was first confirmed. + uint32 confirmation_height = 8; } message WaitingCloseChannel { @@ -2980,6 +3002,7 @@ message ChannelEventUpdate { ChannelPoint inactive_channel = 4; PendingUpdate pending_open_channel = 6; ChannelPoint fully_resolved_channel = 7; + ChannelPoint channel_funding_timeout = 8; } enum UpdateType { @@ -2989,6 +3012,7 @@ message ChannelEventUpdate { INACTIVE_CHANNEL = 3; PENDING_OPEN_CHANNEL = 4; FULLY_RESOLVED_CHANNEL = 5; + CHANNEL_FUNDING_TIMEOUT = 6; } UpdateType type = 5; @@ -3163,10 +3187,10 @@ message QueryRoutesRequest { map dest_custom_records = 13; /* - The channel id of the channel that must be taken to the first hop. If zero, - any channel may be used. + 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. */ - uint64 outgoing_chan_id = 14 [jstype = JS_STRING]; + uint64 outgoing_chan_id = 14 [jstype = JS_STRING, deprecated = true]; /* The pubkey of the last hop of the route. If empty, any hop may be used. @@ -3201,6 +3225,12 @@ message QueryRoutesRequest { only, to 1 to optimize for reliability only or a value inbetween for a mix. */ double time_pref = 18; + + /* + The channel ids of the channels allowed for the first hop. If empty, any + channel may be used. + */ + repeated uint64 outgoing_chan_ids = 20; } message NodePair { @@ -3421,6 +3451,10 @@ message NodeInfoRequest { // If true, will include all known channels associated with the node. bool include_channels = 2; + + // If true, will include announcements' signatures into ChannelEdge. + // Depends on include_channels. + bool include_auth_proof = 3; } message NodeInfo { @@ -3474,13 +3508,39 @@ message RoutingPolicy { uint64 max_htlc_msat = 6; uint32 last_update = 7; - // Custom channel update tlv records. + // Custom channel update tlv records. These are customized fields that are + // not defined by LND and cannot be extracted. map custom_records = 8; int32 inbound_fee_base_msat = 9; int32 inbound_fee_rate_milli_msat = 10; } +/* +ChannelAuthProof is the authentication proof (the signature portion) for a +channel. Using the four signatures contained in the struct, and some +auxiliary knowledge (the funding script, node identities, and outpoint) nodes +on the network are able to validate the authenticity and existence of a +channel. +*/ +message ChannelAuthProof { + // node_sig1 are the raw bytes of the first node signature encoded + // in DER format. + bytes node_sig1 = 1; + + // bitcoin_sig1 are the raw bytes of the first bitcoin signature of the + // MultiSigKey key of the channel encoded in DER format. + bytes bitcoin_sig1 = 2; + + // node_sig2 are the raw bytes of the second node signature encoded + // in DER format. + bytes node_sig2 = 3; + + // bitcoin_sig2 are the raw bytes of the second bitcoin signature of the + // MultiSigKey key of the channel encoded in DER format. + bytes bitcoin_sig2 = 4; +} + /* A fully authenticated channel along with all its unique attributes. Once an authenticated channel announcement has been processed on the network, @@ -3509,6 +3569,13 @@ message ChannelEdge { // Custom channel announcement tlv records. map custom_records = 9; + + // Authentication proof for this channel. This proof contains a set of + // signatures binding four identities, which attests to the legitimacy of + // the advertised channel. This only is available for advertised channels. + // This field is not filled by default. Pass include_auth_proof flag to + // DescribeGraph, GetNodeInfo or GetChanInfo to get this data. + ChannelAuthProof auth_proof = 10; } message ChannelGraphRequest { @@ -3518,6 +3585,9 @@ message ChannelGraphRequest { channels, and public channels that are not yet announced to the network. */ bool include_unannounced = 1; + + // If true, will include announcements' signatures into ChannelEdge. + bool include_auth_proof = 2; } // Returns a new instance of the directed channel graph. @@ -3569,6 +3639,9 @@ message ChanInfoRequest { // 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; + + // If true, will include announcements' signatures into ChannelEdge. + bool include_auth_proof = 3; } message NetworkInfoRequest { @@ -4002,6 +4075,12 @@ message BlindedPathConfig { blinded paths. */ repeated bytes node_omission_list = 4; + + /* + The chained channels list specified via channel id (separated by commas), + starting from a channel owned by the receiver node. + */ + repeated uint64 incoming_channel_list = 5; } enum InvoiceHTLCState { @@ -4183,6 +4262,16 @@ message InvoiceSubscription { uint64 settle_index = 2; } +message DelCanceledInvoiceReq { + // Invoice payment hash to delete. + string invoice_hash = 1; +} + +message DelCanceledInvoiceResp { + // The status of the delete operation. + string status = 1; +} + enum PaymentFailureReason { /* Payment isn't failed (yet). @@ -4665,6 +4754,14 @@ message ForwardingHistoryRequest { // Informs the server if the peer alias should be looked up for each // forwarding event. bool peer_alias_lookup = 5; + + // List of incoming channel ids to filter htlcs received from a + // particular channel + repeated uint64 incoming_chan_ids = 6; + + // List of outgoing channel ids to filter htlcs being forwarded to a + // particular channel + repeated uint64 outgoing_chan_ids = 7; } message ForwardingEvent { // Timestamp is the time (unix epoch offset) that this circuit was @@ -4710,6 +4807,14 @@ message ForwardingEvent { // The peer alias of the outgoing channel. string peer_alias_out = 13; + // The ID of the incoming HTLC in the payment circuit. This field is + // optional and is unset for forwarding events happened before v0.20. + optional uint64 incoming_htlc_id = 14; + + // The ID of the outgoing HTLC in the payment circuit. This field is + // optional and may be unset for legacy forwarding events. + optional uint64 outgoing_htlc_id = 15; + // TODO(roasbeef): add settlement latency? // * use FPE on the chan id? // * also list failures? @@ -5041,9 +5146,37 @@ message Op { } message CheckMacPermRequest { + // The macaroon to check permissions for, serialized in binary format. For + // a macaroon to be valid, it must have been issued by lnd, must succeed all + // caveat conditions, and must contain all of the permissions specified in + // the permissions field. bytes macaroon = 1; + + // The list of permissions the macaroon should be checked against. Only if + // the macaroon contains all of these permissions, it is considered valid. + // If the list of permissions given is empty, then the macaroon is + // considered valid only based on issuance authority and caveat validity. + // An empty list of permissions is therefore equivalent to saying "skip + // checking permissions" (unless check_default_perms_from_full_method is + // specified). repeated MacaroonPermission permissions = 2; + + // The RPC method to check the macaroon against. This is only used if there + // are custom `uri:./` permissions in + // the permission list above. To check a macaroon against the list of + // permissions of a certain RPC method, query the `ListPermissions` RPC + // first, extract the permissions for the method, and then pass them in the + // `permissions` field above. string fullMethod = 3; + + // If this field is set to true, then the permissions list above MUST be + // empty. The default permissions for the provided fullMethod will be used + // to check the macaroon. This is equivalent to looking up the permissions + // for a method in the `ListPermissions` RPC and then calling this RPC with + // the permission list returned from that call. Without this flag, the list + // of permissions must be non-empty for the check to actually perform a + // permission check. + bool check_default_perms_from_full_method = 4; } message CheckMacPermResponse { diff --git a/protos/lnd/v0.20.0-beta/peersrpc/peers.proto b/protos/lnd/v0.20.0-beta/peersrpc/peers.proto new file mode 100644 index 0000000..9e6ac84 --- /dev/null +++ b/protos/lnd/v0.20.0-beta/peersrpc/peers.proto @@ -0,0 +1,94 @@ +syntax = "proto3"; + +package peersrpc; + +import "lightning.proto"; + +option go_package = "github.com/lightningnetwork/lnd/lnrpc/peersrpc"; + +// Peers is a service that can be used to get information and interact +// with the other nodes of the network. +service Peers { + /* lncli: peers updatenodeannouncement + UpdateNodeAnnouncement allows the caller to update the node parameters + and broadcasts a new version of the node announcement to its peers. + */ + rpc UpdateNodeAnnouncement (NodeAnnouncementUpdateRequest) + returns (NodeAnnouncementUpdateResponse); +} + +// UpdateAction is used to determine the kind of action we are referring to. +enum UpdateAction { + // ADD indicates this is an "insertion" kind of action. + ADD = 0; + + // REMOVE indicates this is a "deletion" kind of action. + REMOVE = 1; +} + +enum FeatureSet { + /* + SET_INIT identifies features that should be sent in an Init message to + a remote peer. + */ + SET_INIT = 0; + + /* + SET_LEGACY_GLOBAL identifies features that should be set in the legacy + GlobalFeatures field of an Init message, which maintains backwards + compatibility with nodes that haven't implemented flat features. + */ + SET_LEGACY_GLOBAL = 1; + + /* + SET_NODE_ANN identifies features that should be advertised on node + announcements. + */ + SET_NODE_ANN = 2; + + /* + SET_INVOICE identifies features that should be advertised on invoices + generated by the daemon. + */ + SET_INVOICE = 3; + + /* + SET_INVOICE_AMP identifies the features that should be advertised on + AMP invoices generated by the daemon. + */ + SET_INVOICE_AMP = 4; +} + +message UpdateAddressAction { + // Determines the kind of action. + UpdateAction action = 1; + + // The address used to apply the update action. + string address = 2; +} + +message UpdateFeatureAction { + // Determines the kind of action. + UpdateAction action = 1; + + // The feature bit used to apply the update action. + lnrpc.FeatureBit feature_bit = 2; +} + +message NodeAnnouncementUpdateRequest { + // Set of changes for the features that the node supports. + repeated UpdateFeatureAction feature_updates = 1; + + // Color is the node's color in hex code format. + string color = 2; + + // Alias or nick name of the node. + string alias = 3; + + // Set of changes for the node's known addresses. + repeated UpdateAddressAction address_updates = 4; +} + +message NodeAnnouncementUpdateResponse { + repeated lnrpc.Op ops = 1; +} diff --git a/protos/lnd/v0.19.1-beta/routerrpc/router.proto b/protos/lnd/v0.20.0-beta/routerrpc/router.proto similarity index 98% rename from protos/lnd/v0.19.1-beta/routerrpc/router.proto rename to protos/lnd/v0.20.0-beta/routerrpc/router.proto index 2c2622a..9e305e3 100644 --- a/protos/lnd/v0.19.1-beta/routerrpc/router.proto +++ b/protos/lnd/v0.20.0-beta/routerrpc/router.proto @@ -195,6 +195,13 @@ service Router { */ rpc XDeleteLocalChanAliases (DeleteAliasesRequest) returns (DeleteAliasesResponse); + + /* + XFindBaseLocalChanAlias is an experimental API that looks up the base scid + for a local chan alias that was registered during the current runtime. + */ + rpc XFindBaseLocalChanAlias (FindBaseAliasRequest) + returns (FindBaseAliasResponse); } message SendPaymentRequest { @@ -1116,4 +1123,14 @@ message DeleteAliasesRequest { message DeleteAliasesResponse { repeated lnrpc.AliasMap alias_maps = 1; +} + +message FindBaseAliasRequest { + // The alias we want to look up the base scid for. + uint64 alias = 1; +} + +message FindBaseAliasResponse { + // The base scid that resulted from the base scid look up. + uint64 base = 1; } \ No newline at end of file diff --git a/protos/lnd/v0.19.1-beta/signrpc/signer.proto b/protos/lnd/v0.20.0-beta/signrpc/signer.proto similarity index 100% rename from protos/lnd/v0.19.1-beta/signrpc/signer.proto rename to protos/lnd/v0.20.0-beta/signrpc/signer.proto diff --git a/protos/lnd/v0.20.0-beta/stateservice.proto b/protos/lnd/v0.20.0-beta/stateservice.proto new file mode 100644 index 0000000..97a78d3 --- /dev/null +++ b/protos/lnd/v0.20.0-beta/stateservice.proto @@ -0,0 +1,73 @@ +syntax = "proto3"; + +package lnrpc; + +option go_package = "github.com/lightningnetwork/lnd/lnrpc"; + +/* + * Comments in this file will be directly parsed into the API + * Documentation as descriptions of the associated method, message, or field. + * These descriptions should go right above the definition of the object, and + * can be in either block or // comment format. + * + * An RPC method can be matched to an lncli command by placing a line in the + * beginning of the description in exactly the following format: + * lncli: `methodname` + * + * Failure to specify the exact name of the command will cause documentation + * generation to fail. + * + * More information on how exactly the gRPC documentation is generated from + * this proto file can be found here: + * https://github.com/lightninglabs/lightning-api + */ + +// State service is a always running service that exposes the current state of +// the wallet and RPC server. +service State { + // SubscribeState subscribes to the state of the wallet. The current wallet + // state will always be delivered immediately. + rpc SubscribeState (SubscribeStateRequest) + returns (stream SubscribeStateResponse); + + // GetState returns the current wallet state without streaming further + // changes. + rpc GetState (GetStateRequest) returns (GetStateResponse); +} + +enum WalletState { + // NON_EXISTING means that the wallet has not yet been initialized. + NON_EXISTING = 0; + + // LOCKED means that the wallet is locked and requires a password to unlock. + LOCKED = 1; + + // UNLOCKED means that the wallet was unlocked successfully, but RPC server + // isn't ready. + UNLOCKED = 2; + + // RPC_ACTIVE means that the lnd server is active but not fully ready for + // calls. + RPC_ACTIVE = 3; + + // SERVER_ACTIVE means that the lnd server is ready to accept calls. + SERVER_ACTIVE = 4; + + // WAITING_TO_START means that node is waiting to become the leader in a + // cluster and is not started yet. + WAITING_TO_START = 255; +} + +message SubscribeStateRequest { +} + +message SubscribeStateResponse { + WalletState state = 1; +} + +message GetStateRequest { +} + +message GetStateResponse { + WalletState state = 1; +} diff --git a/protos/lnd/v0.19.1-beta/walletrpc/walletkit.proto b/protos/lnd/v0.20.0-beta/walletrpc/walletkit.proto similarity index 100% rename from protos/lnd/v0.19.1-beta/walletrpc/walletkit.proto rename to protos/lnd/v0.20.0-beta/walletrpc/walletkit.proto diff --git a/protos/lnd/v0.19.1-beta/walletunlocker.proto b/protos/lnd/v0.20.0-beta/walletunlocker.proto similarity index 100% rename from protos/lnd/v0.19.1-beta/walletunlocker.proto rename to protos/lnd/v0.20.0-beta/walletunlocker.proto diff --git a/protos/lnd/v0.19.1-beta/watchtowerrpc/watchtower.proto b/protos/lnd/v0.20.0-beta/watchtowerrpc/watchtower.proto similarity index 100% rename from protos/lnd/v0.19.1-beta/watchtowerrpc/watchtower.proto rename to protos/lnd/v0.20.0-beta/watchtowerrpc/watchtower.proto diff --git a/protos/lnd/v0.19.1-beta/wtclientrpc/wtclient.proto b/protos/lnd/v0.20.0-beta/wtclientrpc/wtclient.proto similarity index 100% rename from protos/lnd/v0.19.1-beta/wtclientrpc/wtclient.proto rename to protos/lnd/v0.20.0-beta/wtclientrpc/wtclient.proto diff --git a/protos/loop/v0.31.2-beta/client.proto b/protos/loop/v0.31.7-beta/client.proto similarity index 94% rename from protos/loop/v0.31.2-beta/client.proto rename to protos/loop/v0.31.7-beta/client.proto index b1247e9..eba7aca 100644 --- a/protos/loop/v0.31.2-beta/client.proto +++ b/protos/loop/v0.31.7-beta/client.proto @@ -100,6 +100,11 @@ service SwapClient { */ rpc GetInfo (GetInfoRequest) returns (GetInfoResponse); + /* loop: `stop` + StopDaemon instructs the daemon to shut down gracefully. + */ + rpc StopDaemon (StopDaemonRequest) returns (StopDaemonResponse); + /* loop: `getparams` GetLiquidityParams gets the parameters that the daemon's liquidity manager is currently configured with. This may be nil if nothing is configured. @@ -202,6 +207,12 @@ service SwapClient { returns (StaticAddressLoopInResponse); } +message StopDaemonRequest { +} + +message StopDaemonResponse { +} + message LoopOutRequest { /* Requested swap amount in sat. This does not include the swap and miner fee. @@ -775,7 +786,10 @@ message OutTermsResponse { message QuoteRequest { /* - The amount to swap in satoshis. + The amount to swap in satoshis. In the loop-in case this can either be taken + from the connected lnd wallet or coin-selected from static address deposits. + This is controlled by the select_deposits flag. If deposit_outpoints are + specified, the coins are taken out of that. */ int64 amt = 1; @@ -823,8 +837,9 @@ message QuoteRequest { /* Static address deposit outpoints that will be quoted for. This option only - pertains to loop in swaps. Either this or the amt parameter can be set at - the same time. + pertains to loop in swaps. If the amt field is set as well the respective + partial amount will be swapped. Cannot be used in conjunction with + auto_select_deposits. */ repeated string deposit_outpoints = 8; @@ -833,6 +848,21 @@ message QuoteRequest { be returned in the specified asset. */ AssetLoopOutRequest asset_info = 9; + + /* + In the legacy loop-in case this field must be set to false. + If set to true, the swap amount will be automatically selected from the + static address deposits. If set to true, deposit_outpoints must be empty. + This option only pertains to loop in swaps. + */ + bool auto_select_deposits = 10; + + /* + If set to true the server will immediately publish the swap in exchange for + a higher fee. This can be useful if the client expects change from a swap. + Note that this feature is only available for static address loop in swaps. + */ + bool fast = 11; } message InQuoteResponse { @@ -862,6 +892,13 @@ message InQuoteResponse { The confirmation target to be used to publish the on-chain HTLC. */ int32 conf_target = 6; + + /* + If the quote request was for a static address loop in and only contained + deposit outpoints the quote response will return the total amount of the + selected deposits. + */ + int64 quoted_amt = 7; } message OutQuoteResponse { @@ -1243,6 +1280,13 @@ message LiquidityParameters { * not be able to be batched with other swaps. */ bool fast_swap_publication = 26; + + /* + A list of peers (their public keys) that should be excluded from the easy + autoloop run. If set, channels connected to these peers won't be + considered for easy autoloop swaps. + */ + repeated bytes easy_autoloop_excluded_peers = 27; } message EasyAssetAutoloopParams { @@ -1910,6 +1954,12 @@ message Deposit { loop-in swap anymore. */ int64 blocks_until_expiry = 6; + + /* + The swap hash of the swap that this deposit is part of. This field is only + set if the deposit is part of a loop-in swap. + */ + bytes swap_hash = 7; } message StaticAddressWithdrawal { @@ -1971,6 +2021,11 @@ message StaticAddressLoopInSwap { fees. */ int64 payment_request_amount_satoshis = 5; + + /* + The deposits that were used for this swap. + */ + repeated Deposit deposits = 6; } enum StaticAddressLoopInSwapState { @@ -2078,6 +2133,24 @@ message StaticAddressLoopInRequest { side and the client can retry the swap with different parameters. */ uint32 payment_timeout_seconds = 8; + + /* + The optional swap amount the client is attempting to swap. It can be + provided in combination with the outpoints or separately. If provided with + outpoints the client takes out this amount from the sum of provided + outpoints and sends the change back to the static address. If the amount is + provided without outpoints, the client will select deposits automatically. + The coin selection strategy is simplified by sorting all available deposits + in descending order by amount, and equal amounts in ascending order of + blocks until expiry, and then selecting the largest deposits first until the + amount is reached. The change will be sent back to the static address. If a + subset of outpoints suffice to cover the specified amount the swap will be + canceled to allow the user to safe on transaction fees. + */ + int64 amount = 9; + + // If set, request the server to use fast publication behavior. + bool fast = 10; } message StaticAddressLoopInResponse { @@ -2142,6 +2215,28 @@ message StaticAddressLoopInResponse { side and the client can retry the swap with different parameters. */ uint32 payment_timeout_seconds = 11; + + /* + The deposits that are used for this swap. + */ + repeated Deposit used_deposits = 12; + + /* + The amount that is being swapped (may be less than total deposit value if + change is returned). + */ + uint64 swap_amount = 13; + + /* + The change amount that will be returned to the static address. + */ + int64 change = 14; + + /* + If set, indicates that the server was requested to use fast publication + behavior. + */ + bool fast = 15; } message AssetLoopOutRequest { diff --git a/protos/loop/v0.31.2-beta/debug.proto b/protos/loop/v0.31.7-beta/debug.proto similarity index 100% rename from protos/loop/v0.31.2-beta/debug.proto rename to protos/loop/v0.31.7-beta/debug.proto diff --git a/protos/loop/v0.31.2-beta/swapserverrpc/common.proto b/protos/loop/v0.31.7-beta/swapserverrpc/common.proto similarity index 100% rename from protos/loop/v0.31.2-beta/swapserverrpc/common.proto rename to protos/loop/v0.31.7-beta/swapserverrpc/common.proto diff --git a/protos/loop/v0.31.2-beta/swapserverrpc/server.proto b/protos/loop/v0.31.7-beta/swapserverrpc/server.proto similarity index 96% rename from protos/loop/v0.31.2-beta/swapserverrpc/server.proto rename to protos/loop/v0.31.7-beta/swapserverrpc/server.proto index 23195a8..26d69a0 100644 --- a/protos/loop/v0.31.2-beta/swapserverrpc/server.proto +++ b/protos/loop/v0.31.7-beta/swapserverrpc/server.proto @@ -294,6 +294,10 @@ message ServerLoopInQuoteRequest { // service fee. This is to cover for the increased on-chain fee the server // has to pay when the sweeping transaction is broadcast. uint32 num_static_address_deposits = 7; + + // If set, request the server to use fast publication behavior. Note that + // this falg is only available for static address loop ins. + bool fast = 8; } message ServerLoopInQuoteResponse { @@ -660,6 +664,12 @@ message FetchL402Response { // SubscribeNotificationsRequest is a request to subscribe to notifications. message SubscribeNotificationsRequest { + enum ListenerVersion { + LEGACY = 0; + V1 = 1; + } + + ListenerVersion version = 1; } // SubscribeNotificationsResponse is a response to a @@ -668,6 +678,7 @@ message SubscribeNotificationsResponse { oneof notification { ServerReservationNotification reservation_notification = 1; ServerStaticLoopInSweepNotification static_loop_in_sweep = 2; + ServerUnfinishedSwapNotification unfinished_swap = 3; } } @@ -687,3 +698,14 @@ message ServerStaticLoopInSweepNotification { // The prevout information of the sweep txn. repeated PrevoutInfo prevout_info = 4; } + +// ServerUnfinishedSwapNotification notifies the client about an unfinished +// swap that needs attention. This is useful in client data loss scenarios to +// help the client recover the swap. +message ServerUnfinishedSwapNotification { + // The swap hash of the unfinished swap. + bytes swap_hash = 1; + + // Whether the swap is a loop in or loop out. + bool is_loop_in = 2; +} diff --git a/protos/pool/v0.6.6-beta/auctioneerrpc/auctioneer.proto b/protos/pool/v0.6.4-beta/auctioneerrpc/auctioneer.proto similarity index 99% rename from protos/pool/v0.6.6-beta/auctioneerrpc/auctioneer.proto rename to protos/pool/v0.6.4-beta/auctioneerrpc/auctioneer.proto index dae9d6b..a753511 100644 --- a/protos/pool/v0.6.6-beta/auctioneerrpc/auctioneer.proto +++ b/protos/pool/v0.6.4-beta/auctioneerrpc/auctioneer.proto @@ -373,11 +373,6 @@ enum ChannelType { outputs that pay directly to the channel initiator (the seller). */ SCRIPT_ENFORCED_LEASE = 2; - - /* - A channel type that uses a Pay-to-Taproot output for the funding output. - */ - SIMPLE_TAPROOT = 3; } message ChannelInfo { @@ -902,11 +897,6 @@ enum OrderChannelType { channel initiator/seller. */ ORDER_CHANNEL_TYPE_SCRIPT_ENFORCED = 2; - - /* - A channel type that uses a Pay-to-Taproot output for the funding output. - */ - ORDER_CHANNEL_TYPE_SIMPLE_TAPROOT = 3; } enum AuctionType { diff --git a/protos/pool/v0.6.6-beta/auctioneerrpc/hashmail.proto b/protos/pool/v0.6.4-beta/auctioneerrpc/hashmail.proto similarity index 100% rename from protos/pool/v0.6.6-beta/auctioneerrpc/hashmail.proto rename to protos/pool/v0.6.4-beta/auctioneerrpc/hashmail.proto diff --git a/protos/pool/v0.6.6-beta/trader.proto b/protos/pool/v0.6.4-beta/trader.proto similarity index 100% rename from protos/pool/v0.6.6-beta/trader.proto rename to protos/pool/v0.6.4-beta/trader.proto diff --git a/protos/tapd/v0.6.0/assetwalletrpc/assetwallet.proto b/protos/tapd/v0.7.0/assetwalletrpc/assetwallet.proto similarity index 88% rename from protos/tapd/v0.6.0/assetwalletrpc/assetwallet.proto rename to protos/tapd/v0.7.0/assetwalletrpc/assetwallet.proto index 0f521e3..82ec6d7 100644 --- a/protos/tapd/v0.6.0/assetwalletrpc/assetwallet.proto +++ b/protos/tapd/v0.7.0/assetwalletrpc/assetwallet.proto @@ -1,5 +1,6 @@ syntax = "proto3"; +import "tapcommon.proto"; import "taprootassets.proto"; package assetwalletrpc; @@ -97,7 +98,7 @@ service AssetWallet { rpc VerifyAssetOwnership (VerifyAssetOwnershipRequest) returns (VerifyAssetOwnershipResponse); - /* + /* `tapcli: assets removelease` RemoveUTXOLease removes the lease/lock/reservation of the given managed UTXO. */ @@ -192,10 +193,24 @@ message TxTemplate { repeated PrevId inputs = 1; /* - A map of all Taproot Asset addresses mapped to the anchor transaction's - output index that should be sent to. + DEPRECATED: A map of all Taproot Asset addresses that should be sent to. + The keys are the Taproot Asset addresses in human-readable form, and the + values are IGNORED and should not be set (use the addresses_with_amounts + field below instead). The recipients map and addresses_with_amounts list + are mutually exclusive, meaning that if addresses_with_amounts is set, then + recipients must be empty, and vice versa. */ map recipients = 2; + + /* + A list of addresses and the amounts of asset units to send to them. This + must be used for V2 TAP addresses that don't specify an amount in the + address itself and allow the sender to choose the amount to send. The + recipients and addresses_with_amounts lists are mutually exclusive, + meaning that if addresses_with_amounts is set, then recipients must be + empty, and vice versa. + */ + repeated taprpc.AddressWithAmount addresses_with_amounts = 3; } message PrevId { @@ -416,18 +431,23 @@ message PublishAndLogRequest { } message NextInternalKeyRequest { + // The key family to derive the next internal key for. uint32 key_family = 1; } message NextInternalKeyResponse { + // The full key descriptor of the internal key that was derived. taprpc.KeyDescriptor internal_key = 1; } message NextScriptKeyRequest { + // The key family to derive the next script key for. uint32 key_family = 1; } message NextScriptKeyResponse { + // The full script key information that was derived, including the + // internal key and the tweaked script key. taprpc.ScriptKey script_key = 1; } @@ -438,6 +458,7 @@ message QueryInternalKeyRequest { } message QueryInternalKeyResponse { + // The full key descriptor of the internal key that was queried. taprpc.KeyDescriptor internal_key = 1; } @@ -449,14 +470,21 @@ message QueryScriptKeyRequest { } message QueryScriptKeyResponse { + // The full script key information that was queried, including the + // internal key and the tweaked script key. taprpc.ScriptKey script_key = 1; } message ProveAssetOwnershipRequest { + // The asset ID of the asset to prove ownership of. This is the 32-byte + // asset ID that identifies a particular asset or tranche of assets. bytes asset_id = 1; + // The script key that is used to spend the asset. bytes script_key = 2; + // The outpoint of the asset UTXO that is being proven to be owned by the + // prover. taprpc.OutPoint outpoint = 3; // An optional 32-byte challenge that may be used to bind the generated @@ -470,6 +498,8 @@ message ProveAssetOwnershipResponse { } message VerifyAssetOwnershipRequest { + // The full ownership proof that was generated, including the witness data + // that contains the proving signature. bytes proof_with_witness = 1; // An optional 32-byte challenge that may be used to check the ownership @@ -479,6 +509,7 @@ message VerifyAssetOwnershipRequest { } message VerifyAssetOwnershipResponse { + // Whether the ownership proof is valid or not. bool valid_proof = 1; // The outpoint the proof commits to. @@ -506,9 +537,12 @@ message RemoveUTXOLeaseResponse { } message DeclareScriptKeyRequest { + // The script key the wallet should be informed about. taprpc.ScriptKey script_key = 1; } message DeclareScriptKeyResponse { + // The script key that was declared, including the internal key and the + // tweaked script key. taprpc.ScriptKey script_key = 1; } diff --git a/protos/tapd/v0.7.0/authmailboxrpc/mailbox.proto b/protos/tapd/v0.7.0/authmailboxrpc/mailbox.proto new file mode 100644 index 0000000..ffb7deb --- /dev/null +++ b/protos/tapd/v0.7.0/authmailboxrpc/mailbox.proto @@ -0,0 +1,249 @@ +syntax = "proto3"; + +import "tapcommon.proto"; + +package authmailboxrpc; + +option go_package = "github.com/lightninglabs/taproot-assets/taprpc/authmailboxrpc"; + +/* +Service definition for the authenticated mailbox. This service allows sending +messages (authenticated by UTXO proof) and receiving messages (authenticated +via a challenge-response handshake). +*/ +service Mailbox { + /* + Sends a single message to a receiver's mailbox. Requires a valid, unused + Bitcoin P2TR transaction outpoint as proof of uniqueness, included in a + block as proof of work. + */ + rpc SendMessage (SendMessageRequest) returns (SendMessageResponse); + + /* + Initiates a bidirectional stream to receive messages for a specific + receiver. This stream implements the challenge-response handshake required + for receiver authentication before messages are delivered. + + Expected flow: + 1. Client -> Server: ReceiveMessagesRequest(init = InitReceive{...}) + 2. Server -> Client: ReceiveMessagesResponse(challenge = Challenge{...}) + 3. Client -> Server: ReceiveMessagesRequest(auth_sig = AuthSignature{...}) + 4. Server -> Client: [Stream of ReceiveMessagesResponse( + message = MailboxMessage{...} + )] + 5. Server -> Client: ReceiveMessagesResponse(eos = EndOfStream{}) + */ + rpc ReceiveMessages (stream ReceiveMessagesRequest) + returns (stream ReceiveMessagesResponse); + + /* + Returns basic server information. + */ + rpc MailboxInfo (MailboxInfoRequest) returns (MailboxInfoResponse); +} + +// Represents the Merkle proof hashes needed to link a transaction to the Merkle +// root within a Bitcoin block header. +message MerkleProof { + // List of sibling hashes in the Merkle path, ordered from the transaction's + // sibling up towards the root. Each hash is typically 32 bytes. + repeated bytes sibling_hashes = 1; + + // The bitmask indicating the direction (left/right) of each sibling hash + // in the Merkle tree. Each bit corresponds to a sibling hash in the + // sibling_hashes list. 0 indicates left, 1 indicates right. + repeated bool bits = 2; +} + +// Encapsulates the full proof required for sender authentication, demonstrating +// that a specific P2TR transaction output was included in a Bitcoin block. To +// prove knowledge of the claimed output, the proof must include the output's +// internal key and, optionally, the Taproot Merkle root. +message BitcoinMerkleInclusionProof { + // The raw Bitcoin transaction bytes, in standard Bitcoin serialization + // format, containing the outpoint being claimed. The server will hash this + // to get the TXID. + bytes raw_tx_data = 1; + + // The raw block header bytes (typically 80 bytes) of the block in which the + // transaction was mined. Contains the Merkle root against which the proof + // is verified. + bytes raw_block_header_data = 2; + + // The height at which the block was mined. This is used to determine the + // block's validity and to ensure the transaction is not too old. + uint32 block_height = 3; + + // The Merkle path proving the transaction's inclusion in the block header's + // Merkle root. + MerkleProof merkle_proof = 4; + + // The specific output within the provided transaction being claimed as the + // proof "token". The output at the given index must be a P2TR output. + // The server must verify that the txid_hex matches the hash of the provided + // transaction data, and that this specific outpoint index exists in the + // transaction. + taprpc.OutPoint claimed_outpoint = 5; + + // The Taproot internal key used to construct the P2TR output that is + // claimed by the outpoint above. Must be provided alongside the Taproot + // Merkle root to prove knowledge of the output's construction. + bytes internal_key = 6; + + // The Taproot Merkle root, if applicable. This, alongside the internal key, + // is used to prove knowledge of the output's construction. If this is not + // provided (empty or nil), a BIP-0086 construction is assumed. + bytes merkle_root = 7; +} + +// Represents a single message as stored and retrieved from the mailbox. +message MailboxMessage { + // The unique ID assigned to the message by the server upon storage. + uint64 message_id = 1; + + // The ECIES encrypted message payload, intended for the receiver. + bytes encrypted_payload = 2; + + // Timestamp (Unix epoch seconds) when the message arrived at the server. + int64 arrival_timestamp = 3; +} + +// Represents a list of messages. +message MailboxMessages { + // The list of mailbox messages. + repeated MailboxMessage messages = 1; +} + +// Request message for the SendMessage RPC. +message SendMessageRequest { + // The public key identifier of the intended receiver (ReceiverID), encoded + // as the raw bytes of the compressed public key. + bytes receiver_id = 1; + + // The ECIES encrypted message payload. + bytes encrypted_payload = 2; + + // A proof of the sender's identity, typically a Bitcoin transaction or + // another proof that work was done to create the message. + oneof proof { + // The Bitcoin Merkle Inclusion Proof used as the sender's + // authentication. The server MUST perform full validation of this + // proof: + // 1. Verify claimed_outpoint.txid_hex matches hash(raw_tx_data). + // 2. Verify claimed_outpoint.index is valid for the transaction. + // 3. Verify merkle_proof connects the transaction hash to the + // raw_block_header_data's Merkle root. + // 4. Verify block_header validity (e.g., PoW, potentially chain + // context). + // 5. Ensure the claimed_outpoint has not been used previously (check + // used_proofs table). + BitcoinMerkleInclusionProof tx_proof = 4; + } +} + +// Response message for the SendMessage RPC. +message SendMessageResponse { + // The unique ID assigned to the stored message by the server. + uint64 message_id = 1; +} + +// Wrapper message for requests sent FROM the client TO the server during the +// ReceiveMessages stream. +message ReceiveMessagesRequest { + oneof request_type { + // The initial parameters sent by the client to start receiving + // messages. + InitReceive init = 1; + + // The client's signature in response to the server's challenge. + AuthSignature auth_sig = 2; + } +} + +// Carries the initial parameters from the client to start receiving messages. +message InitReceive { + // The public key identifier of the receiver of the messages that should be + // received through a message receive stream, encoded as the raw bytes of + // the compressed public key. + bytes receiver_id = 1; + + // The exclusive start message ID, meaning messages with this ID or higher + // will be included in the response. This allows the client to resume + // receiving messages from a specific point without missing any. One of + // start_message_id_exclusive, start_block_height_inclusive or + // start_timestamp_exclusive must be at their non-default values for any + // existing messages to be returned! + uint64 start_message_id_exclusive = 2; + + // The inclusive start block height, meaning messages from this block height + // or higher will be included in the response. This allows the client to + // filter messages based on the block height at which they were produced. + // One of start_message_id_exclusive, start_block_height_inclusive or + // start_timestamp_exclusive must be at their non-default values for any + // existing messages to be returned! + uint32 start_block_height_inclusive = 3; + + // The exclusive start timestamp in Unix epoch seconds, meaning messages + // with a timestamp strictly greater than this value will be included in the + // response. This allows the client to filter messages based on their + // arrival time at the server. One of start_message_id_exclusive, + // start_block_height_inclusive or start_timestamp_exclusive must be at + // their non-default values for any existing messages to be returned! + int64 start_timestamp_exclusive = 4; +} + +// Carries the client's signature in response to the server's challenge. +message AuthSignature { + // The client's Schnorr signature over the challenge hash provided by + // the server. + bytes signature = 1; +} + +// Wrapper message for responses sent FROM the server TO the client +// during the ReceiveMessages stream. +message ReceiveMessagesResponse { + oneof response_type { + // The challenge sent by the server to the client, which the client + // must sign to prove ownership of the receiver's public key. + Challenge challenge = 1; + + // A successful authentication response, indicating the client has + // successfully signed the challenge and is now authenticated to receive + // messages. + bool auth_success = 2; + + // A list of mailbox messages sent to the client. This will be + // sent after the client has successfully authenticated by signing the + // challenge. The client should expect a stream of these messages + // until the server sends an EndOfStream message. + MailboxMessages messages = 3; + + // An EndOfStream message indicating that the server is shutting down. + EndOfStream eos = 4; + } +} + +// Carries the challenge hash sent by the server to the client. +message Challenge { + // The challenge hash that the client must sign to prove ownership of the + // receiver's public key. + bytes challenge_hash = 1; +} + +// An empty message used to explicitly signal the normal end of the message +// stream. +message EndOfStream { +} + +// Request message for the MailboxInfo RPC. +message MailboxInfoRequest { +} + +// Response message for the MailboxInfo RPC. +message MailboxInfoResponse { + // The current server time in Unix epoch seconds. + int64 server_time = 1; + + // The number of messages currently stored on the server. + uint64 message_count = 2; +} diff --git a/protos/tapd/v0.6.0/mintrpc/mint.proto b/protos/tapd/v0.7.0/mintrpc/mint.proto similarity index 95% rename from protos/tapd/v0.6.0/mintrpc/mint.proto rename to protos/tapd/v0.7.0/mintrpc/mint.proto index 6f998eb..3268e93 100644 --- a/protos/tapd/v0.6.0/mintrpc/mint.proto +++ b/protos/tapd/v0.7.0/mintrpc/mint.proto @@ -225,19 +225,16 @@ message MintAsset { taprpc.ExternalKey external_group_key = 14; /* - Enabling this flag allows the creation of universe commitments for a new - asset group. + Enables the supply commitments feature for a new asset group. - Universe commitments are minter-controlled, on-chain attestations that - anchor and verify the state of an asset group. + Supply commitments are minter‑controlled, on‑chain attestations that + anchor and verify the evolving aggregate supply state of an asset group. - This flag imposes restrictions on the minting process by limiting the batch - to assets within the same universe, meaning they share the same group key. - This option is applicable only for the creation of a new asset group - (i.e., the first minting tranche of an asset group) and ensures that the - batch is limited to a single asset group. + When enabled, the batch must be a single asset group (all assets share the + same group key). Valid only for creating a new asset group (the first + minting tranche). */ - bool universe_commitments = 15; + bool enable_supply_commitments = 15; } message MintAssetRequest { diff --git a/protos/tapd/v0.6.0/priceoraclerpc/price_oracle.proto b/protos/tapd/v0.7.0/priceoraclerpc/price_oracle.proto similarity index 55% rename from protos/tapd/v0.6.0/priceoraclerpc/price_oracle.proto rename to protos/tapd/v0.7.0/priceoraclerpc/price_oracle.proto index fd0ab1f..128ca4a 100644 --- a/protos/tapd/v0.6.0/priceoraclerpc/price_oracle.proto +++ b/protos/tapd/v0.7.0/priceoraclerpc/price_oracle.proto @@ -23,6 +23,64 @@ enum TransactionType { SALE = 1; } +// Intent is an enum informing the price oracle about the intent of the price +// rate query. This is used to provide context for the asset rates being +// requested, allowing the price oracle to tailor the response based on the +// specific use case, such as paying an invoice or receiving a payment and the +// different stages involved in those. +enum Intent { + // INTENT_UNSPECIFIED is used to indicate that the intent of the price rate + // query is not specified. This is the fallback default value and should not + // be used in production code. It is primarily used for backward + // compatibility with older versions of the protocol that did not include + // intent information. + INTENT_UNSPECIFIED = 0; + + // INTENT_PAY_INVOICE_HINT is used to indicate that the user is requesting + // a price rate hint for paying an invoice. This is typically used by the + // payer of an invoice to provide a suggestion of the expected asset rate to + // the RFQ peer (edge node) that will determine the actual rate for the + // payment. + INTENT_PAY_INVOICE_HINT = 1; + + // INTENT_PAY_INVOICE is used to indicate that a peer wants to pay an + // invoice with assets. This is typically used by the edge node that + // facilitates the swap from assets to BTC for the payer of an invoice. This + // intent is used to provide the actual asset rate for the payment, which + // may differ from the hint provided by the payer. + INTENT_PAY_INVOICE = 2; + + // INTENT_PAY_INVOICE_QUALIFY is used to indicate that the payer of an + // invoice has received an asset rate from their RFQ peer (edge node) and is + // qualifying the rate for the payment. This is typically used by the payer + // of an invoice to ensure that the asset rate provided by their peer (edge + // node) is acceptable before proceeding with the payment. + INTENT_PAY_INVOICE_QUALIFY = 3; + + // INTENT_RECV_PAYMENT_HINT is used to indicate that the user is requesting + // a price rate hint for receiving a payment through an invoice. This is + // typically used by the creator of an invoice to provide a suggestion of + // the expected asset rate to the RFQ peer (edge node) that will determine + // the actual rate used for creating an invoice. + INTENT_RECV_PAYMENT_HINT = 4; + + // INTENT_RECV_PAYMENT is used to indicate that a peer wants to create an + // invoice to receive a payment with assets. This is typically used by the + // edge node that facilitates the swap from BTC to assets for the receiver + // of a payment. This intent is used to provide the actual asset rate for + // the invoice creation, which may differ from the hint provided by the + // receiver. + INTENT_RECV_PAYMENT = 5; + + // INTENT_RECV_PAYMENT_QUALIFY is used to indicate that the creator of an + // invoice received an asset rate from their RFQ peer (edge node) and is + // qualifying the rate for the creation of the invoice. This is typically + // used by the creator of an invoice to ensure that the asset rate provided + // by their peer (edge node) is acceptable before proceeding with creating + // the invoice. + INTENT_RECV_PAYMENT_QUALIFY = 6; +} + // FixedPoint is a scaled integer representation of a fractional number. // // This type consists of two integer fields: a coefficient and a scale. @@ -129,6 +187,32 @@ message QueryAssetRatesRequest { // 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; + + // intent informs the price oracle about the stage of the payment flow that + // lead to the price rate query. This is used to provide context for the + // asset rates being requested, allowing the price oracle to tailor the + // response based on the specific use case, such as paying an invoice or + // receiving a payment and the different stages involved in those. This + // field will only be set by tapd v0.7.0 and later. + Intent intent = 7; + + // counterparty_id is the 33-byte public key of the peer that is on the + // opposite side of the transaction. This field will only be set by tapd + // v0.7.0 and later and only if the user initiating the transaction (sending + // a payment or creating an invoice) opted in to sharing their peer ID with + // the price oracle. + bytes counterparty_id = 8; + + // metadata is an optional text field that can be used to provide + // additional metadata about the transaction to the price oracle. This can + // include information about the wallet end user that initiated the + // transaction, or any authentication information that the price oracle + // can use to give out a more accurate (or discount) asset rate. Though not + // verified or enforced by tapd, the suggested format for this field is a + // JSON string. This field is optional and can be left empty if no metadata + // is available. The maximum length of this field is 32'768 bytes. This + // field will only be set by tapd v0.7.0 and later. + string metadata = 9; } // QueryAssetRatesOkResponse is the successful response to a diff --git a/protos/tapd/v0.6.0/rfqrpc/rfq.proto b/protos/tapd/v0.7.0/rfqrpc/rfq.proto similarity index 83% rename from protos/tapd/v0.6.0/rfqrpc/rfq.proto rename to protos/tapd/v0.7.0/rfqrpc/rfq.proto index d37acf8..0d472c2 100644 --- a/protos/tapd/v0.6.0/rfqrpc/rfq.proto +++ b/protos/tapd/v0.7.0/rfqrpc/rfq.proto @@ -131,8 +131,7 @@ message AddAssetBuyOrderRequest { // 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. + // 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 @@ -144,6 +143,16 @@ message AddAssetBuyOrderRequest { // the RFQ negotiation to work. This flag shouldn't be set outside of test // scenarios. bool skip_asset_channel_check = 6; + + // An optional text field that can be used to provide additional metadata + // about the buy order to the price oracle. This can include information + // about the wallet end user that initiated the transaction, or any + // authentication information that the price oracle can use to give out a + // more accurate (or discount) asset rate. Though not verified or enforced + // by tapd, the suggested format for this field is a JSON string. + // This field is optional and can be left empty if no metadata is available. + // The maximum length of this field is 32'768 bytes. + string price_oracle_metadata = 7; } message AddAssetBuyOrderResponse { @@ -173,8 +182,7 @@ message AddAssetSellOrderRequest { // 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. + // 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 @@ -186,6 +194,16 @@ message AddAssetSellOrderRequest { // the RFQ negotiation to work. This flag shouldn't be set outside of test // scenarios. bool skip_asset_channel_check = 6; + + // An optional text field that can be used to provide additional metadata + // about the sell order to the price oracle. This can include information + // about the wallet end user that initiated the transaction, or any + // authentication information that the price oracle can use to give out a + // more accurate (or discount) asset rate. Though not verified or enforced + // by tapd, the suggested format for this field is a JSON string. + // This field is optional and can be left empty if no metadata is available. + // The maximum length of this field is 32'768 bytes. + string price_oracle_metadata = 7; } message AddAssetSellOrderResponse { @@ -229,6 +247,16 @@ message AddAssetBuyOfferResponse { message QueryPeerAcceptedQuotesRequest { } +message AssetSpec { + // The 32-byte asset ID specified as raw bytes. + bytes id = 1; + + // The 32-byte asset group public key, serialized in BIP340 format. + // BIP340 defines a canonical encoding for Schnorr public keys. + // This field is serialized using schnorr.SerializePubKey. + bytes group_pub_key = 2; +} + message PeerAcceptedBuyQuote { // Quote counterparty peer. string peer = 1; @@ -258,6 +286,16 @@ message PeerAcceptedBuyQuote { // asset unit equivalent of 354 satoshis, which is the minimum amount for an // HTLC to be above the dust limit. uint64 min_transportable_units = 7; + + // An optional user-provided text field used to provide additional metadata + // about the buy order to the price oracle. This can include information + // about the wallet end user that initiated the transaction, or any + // authentication information that the price oracle can use to give out a + // more accurate (or discount) asset rate. + string price_oracle_metadata = 8; + + // The subject asset specifier. + AssetSpec asset_spec = 9; } message PeerAcceptedSellQuote { @@ -287,6 +325,16 @@ message PeerAcceptedSellQuote { // amount for a non-dust HTLC) plus the equivalent of one asset unit in // milli-satoshis. uint64 min_transportable_msat = 7; + + // An optional user-provided text field used to provide additional metadata + // about the sell order to the price oracle. This can include information + // about the wallet end user that initiated the transaction, or any + // authentication information that the price oracle can use to give out a + // more accurate (or discount) asset rate. + string price_oracle_metadata = 8; + + // The subject asset specifier. + AssetSpec asset_spec = 9; } // QuoteRespStatus is an enum that represents the status of a quote response. diff --git a/protos/tapd/v0.6.0/tapchannelrpc/tapchannel.proto b/protos/tapd/v0.7.0/tapchannelrpc/tapchannel.proto similarity index 75% rename from protos/tapd/v0.6.0/tapchannelrpc/tapchannel.proto rename to protos/tapd/v0.7.0/tapchannelrpc/tapchannel.proto index cbb3ef8..8479fb2 100644 --- a/protos/tapd/v0.6.0/tapchannelrpc/tapchannel.proto +++ b/protos/tapd/v0.7.0/tapchannelrpc/tapchannel.proto @@ -17,6 +17,7 @@ service TaprootAssetChannels { rpc FundChannel (FundChannelRequest) returns (FundChannelResponse); /* + Deprecated. 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 @@ -24,7 +25,9 @@ service TaprootAssetChannels { validation. */ rpc EncodeCustomRecords (EncodeCustomRecordsRequest) - returns (EncodeCustomRecordsResponse); + returns (EncodeCustomRecordsResponse) { + option deprecated = true; + }; /* litcli: `ln sendpayment` SendPayment is a wrapper around lnd's routerrpc.SendPaymentV2 RPC method @@ -100,6 +103,7 @@ message RouterSendPaymentData { message EncodeCustomRecordsRequest { oneof input { + // The custom records to encode for a payment request. RouterSendPaymentData router_send_payment = 1; } } @@ -124,8 +128,8 @@ message SendPaymentRequest { 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. + // out the assets and converting them to satoshis. If set, only a quote with + // this peer may be negotiated to carry out the payment. bytes peer_pubkey = 3; // The full lnd payment request to send. All fields behave the same way as @@ -153,6 +157,23 @@ message SendPaymentRequest { // The group key which dictates which assets may be used for this payment. // Mutually exclusive to asset_id. bytes group_key = 7; + + // An optional text field that can be used to provide additional metadata + // about the payment to the price oracle. This can include information + // about the wallet end user that initiated the transaction, or any + // authentication information that the price oracle can use to give out a + // more accurate (or discount) asset rate. Though not verified or enforced + // by tapd, the suggested format for this field is a JSON string. + // This field is optional and can be left empty if no metadata is available. + // The maximum length of this field is 32'768 bytes. + string price_oracle_metadata = 8; +} + +message AcceptedSellQuotes { + // If swapping of assets is necessary to carry out the payment, a number of + // RFQ quotes may be negotiated for that purpose. The following field + // contains all the sell orders that were negotiated with our peers. + repeated rfqrpc.PeerAcceptedSellQuote accepted_sell_orders = 1; } message SendPaymentResponse { @@ -161,16 +182,26 @@ message SendPaymentResponse { // 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. + // Deprecated. This will now only contain the first quote that was + // negotiated. Since the introduction of multi-rfq we now negotiate + // multiple quotes in the context of a payment. Use the new field named + // "accepted_sell_orders" to retrieve all of them. 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. + // If swapping of assets is necessary to carry out the payment, a number + // of RFQ quotes may be negotiated for that purpose. The following field + // contains all the sell orders that were negotiated with our peers. + AcceptedSellQuotes accepted_sell_orders = 3; + + // 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 { + // The payment hash of the HODL invoice to be created. bytes payment_hash = 1; } @@ -210,6 +241,16 @@ message AddInvoiceRequest { // invoice. If set, any asset that belongs to this group may be accepted to // settle this invoice. Mutually exclusive to asset_id. bytes group_key = 6; + + // An optional text field that can be used to provide additional metadata + // about the invoice to the price oracle. This can include information + // about the wallet end user that initiated the transaction, or any + // authentication information that the price oracle can use to give out a + // more accurate (or discount) asset rate. Though not verified or enforced + // by tapd, the suggested format for this field is a JSON string. + // This field is optional and can be left empty if no metadata is available. + // The maximum length of this field is 32'768 bytes. + string price_oracle_metadata = 7; } message AddInvoiceResponse { @@ -232,6 +273,16 @@ message AssetPayReq { // The group key that will be used to resolve the invoice's satoshi amount. // Mutually exclusive to asset_id. bytes group_key = 3; + + // An optional text field that can be used to provide additional metadata + // about the invoice to the price oracle. This can include information + // about the wallet end user that initiated the transaction, or any + // authentication information that the price oracle can use to give out a + // more accurate (or discount) asset rate. Though not verified or enforced + // by tapd, the suggested format for this field is a JSON string. + // This field is optional and can be left empty if no metadata is available. + // The maximum length of this field is 32'768 bytes. + string price_oracle_metadata = 4; } message AssetPayReqResponse { diff --git a/protos/tapd/v0.7.0/tapcommon.proto b/protos/tapd/v0.7.0/tapcommon.proto new file mode 100644 index 0000000..c761371 --- /dev/null +++ b/protos/tapd/v0.7.0/tapcommon.proto @@ -0,0 +1,36 @@ +syntax = "proto3"; + +package taprpc; + +option go_package = "github.com/lightninglabs/taproot-assets/taprpc"; + +// Represents a Bitcoin transaction outpoint. +message OutPoint { + /* + Raw bytes representing the transaction id. + */ + bytes txid = 1; + + /* + The index of the output on the transaction. + */ + uint32 output_index = 2; +} + +// A transaction outpoint annotated with TAP-level asset metadata. It uniquely +// identifies an asset anchored at a specific outpoint. +message AssetOutPoint { + // The outpoint of the asset anchor, represented as a string in the + // format ":". The is the transaction ID of the UTXO, + // hex-encoded and byte-reversed (i.e., the internal little-endian + // 32-byte value is reversed to big-endian hex format) to match standard + // Bitcoin RPC and UI conventions. + string anchor_out_point = 1; + + // The asset ID of the asset anchored at the outpoint. + bytes asset_id = 2; + + // The script key of the asset. This is the taproot output key that the + // asset is locked to. + bytes script_key = 3; +} diff --git a/protos/tapd/v0.6.0/tapdevrpc/tapdev.proto b/protos/tapd/v0.7.0/tapdevrpc/tapdev.proto similarity index 100% rename from protos/tapd/v0.6.0/tapdevrpc/tapdev.proto rename to protos/tapd/v0.7.0/tapdevrpc/tapdev.proto diff --git a/protos/tapd/v0.6.0/taprootassets.proto b/protos/tapd/v0.7.0/taprootassets.proto similarity index 78% rename from protos/tapd/v0.6.0/taprootassets.proto rename to protos/tapd/v0.7.0/taprootassets.proto index 8cb63f8..05309ad 100644 --- a/protos/tapd/v0.6.0/taprootassets.proto +++ b/protos/tapd/v0.7.0/taprootassets.proto @@ -1,5 +1,7 @@ syntax = "proto3"; +import "tapcommon.proto"; + package taprpc; option go_package = "github.com/lightninglabs/taproot-assets/taprpc"; @@ -127,7 +129,7 @@ service TaprootAssets { 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); + rpc FetchAssetMeta (FetchAssetMetaRequest) returns (FetchAssetMetaResponse); /* tapcli: `events receive` SubscribeReceiveEvents allows a caller to subscribe to receive events for @@ -206,8 +208,19 @@ message AssetMeta { } message ListAssetRequest { + // Whether to include each asset's witness in the response. The witness + // either contains the spending signatures or the split commitment witness, + // which can both be large and usually aren't very useful on the command + // line, so are omitted by default. bool with_witness = 1; + + // Include assets that are marked as spent (which is always true for burn + // or tombstone assets). bool include_spent = 2; + + // Include assets that are leased (locked/reserved) by the daemon for a + // pending transfer. Leased assets cannot be used by the daemon until the + // pending transfer is confirmed or the lease expires. bool include_leased = 3; // List assets that aren't confirmed yet. Only freshly minted assets will @@ -508,6 +521,9 @@ message Asset { // Describes where in the chain the asset is currently anchored. AnchorInfo chain_anchor = 12; + // The asset's previous witnesses, which either contain the spending + // witness stack (usually a signature) or the split commitment witness + // (which is used to prove the split commitment of a split asset). repeated PrevWitness prev_witnesses = 13; // Indicates whether the asset has been spent. @@ -558,18 +574,28 @@ message Asset { } message PrevWitness { + // The previous input asset that this witness is for. PrevInputAsset prev_id = 1; + // The witness stack that is used to prove the asset owner's authorization + // to spend an asset. This is only set if the asset is the root asset of an + // asset split. repeated bytes tx_witness = 2; + // The split commitment that is used to prove the split commitment of a + // split asset. This is only set if the asset is a split asset. SplitCommitment split_commitment = 3; } message SplitCommitment { + // The root asset that contains the transaction witness that authorizes the + // spend of the asset. Asset root_asset = 1; } message ListAssetResponse { + // The list of assets found in the database matching the request query + // parameters. repeated Asset assets = 1; // This is a count of unconfirmed outgoing transfers. Unconfirmed transfers @@ -583,6 +609,9 @@ message ListAssetResponse { } message ListUtxosRequest { + // Whether to include UTXOs that are marked as leased (locked/reserved) by + // the wallet for a pending transfer. Leased UTXOs cannot be used by the + // wallet until the pending transfer is confirmed or the lease expires. bool include_leased = 1; // The script key type to filter the assets by. If not set, only assets with @@ -702,6 +731,9 @@ message AssetBalance { // The balance of the asset owned by the target daemon. uint64 balance = 3; + + // The group key of the asset (if it belongs to a group). + bytes group_key = 4; } message AssetGroupBalance { @@ -713,9 +745,20 @@ message AssetGroupBalance { } message ListBalancesResponse { + // The map of asset balances, where the key is the asset ID and the value + // is the balance of that asset owned by the target daemon. This is only + // set if group_by.asset_id is true in the request. map asset_balances = 1; + // The map of asset group balances, where the key is the group key + // and the value is the balance of that group owned by the target daemon. + // This is only set if group_by.group_key is true in the request. map asset_group_balances = 2; + + // This is a count of unconfirmed outgoing transfers. Unconfirmed transfers + // (and the change resulting from them) do not appear in the balance. The + // balance only represents confirmed assets that are owned by the daemon. + uint64 unconfirmed_transfers = 3; } message ListTransfersRequest { @@ -753,14 +796,22 @@ message ChainHash { } message AssetTransfer { + // The timestamp of the transfer in UTC Unix time seconds. int64 transfer_timestamp = 1; - // The new transaction that commits to the set of Taproot Assets found - // at the above new anchor point. + // The new transaction that commits to the set of Taproot Assets found at + // the above new anchor point. Note that this is in raw byte format, not + // the reversed hex string format that is used for displayed txids. When + // listing assets on the CLI we purposefully use the display format so it + // is easier to copy and paste into other tools. bytes anchor_tx_hash = 2; + // The height hint of the anchor transaction. This is the height at which + // the anchor transaction was published, so the actual inclusion height + // will be greater than this value. uint32 anchor_tx_height_hint = 3; + // The total fees paid by the anchor transaction in satoshis. int64 anchor_tx_chain_fees = 4; // Describes the set of spent assets. @@ -809,19 +860,37 @@ message TransferOutputAnchor { // chain. string outpoint = 1; + // The anchor transaction output's value in satoshis. int64 value = 2; + // The anchor transaction output's internal key, which is the Taproot + // internal key of the on-chain output. bytes internal_key = 3; + // The Taproot Asset root commitment hash, which is the root of the + // Taproot Asset commitment tree for the asset that was created. bytes taproot_asset_root = 4; + // The Taproot merkle root hash committed to by the outpoint of this + // output. If there is no Tapscript sibling, this is equal to the Taproot + // Asset root commitment hash. + // If there is a Tapscript sibling, this is the tap branch root hash of the + // Taproot Asset root hash and the tapscript sibling. bytes merkle_root = 5; + // The serialized preimage of a Tapscript sibling, if there was one. If this + // is empty, then the merkle_root hash is equal to the Taproot root hash + // of the anchor output. bytes tapscript_sibling = 6; + // The number of passive assets that were committed to this output. + // Passive assets are assets that are not actively spent, but are instead + // passively carried along with the main asset and re-anchored in the + // anchor output. uint32 num_passive_assets = 7; - // pk_script is the pkscript of the anchor output. + // The actual output's script, which is the P2TR script for the final + // Taproot output key created by this transfer output. bytes pk_script = 8; } @@ -859,32 +928,65 @@ enum ProofDeliveryStatus { } message TransferOutput { + // The transfer output's on-chain anchor information, which contains the + // BTC-level output information that anchors the Taproot Asset commitment + // for this output. TransferOutputAnchor anchor = 1; + // The script key of the asset that was created. bytes script_key = 2; + // Indicates whether the script key is known to the wallet of the lnd node + // connected to the Taproot Asset daemon. If true, the asset will be shown + // in the wallet balance. bool script_key_is_local = 3; + // The amount of the asset that was created in this output. uint64 amount = 4; // The new individual transition proof (not a full proof file) that proves // the inclusion of the new asset within the new AnchorTx. bytes new_proof_blob = 5; + // The split commitment root hash of the asset that was created in this + // output. This is only set if the asset is a split root output, meaning + // that the asset is a split root output that carries the change from a + // split or a tombstone from a non-interactive full value send output. bytes split_commit_root_hash = 6; + // The type of the output. This is used to distinguish between a simple + // output that is not a split root and does not carry passive assets, and a + // split root output that carries the change from a split or a tombstone + // from a non-interactive full value send output. OutputType output_type = 7; + // The asset version of the output. This is used to determine how the asset + // is encoded in the Taproot Asset commitment tree. AssetVersion asset_version = 8; + // The lock time of the output, which is an optional field that can be set + // to delay the spending of the output until a certain time in the future. uint64 lock_time = 9; + // The relative lock time of the output, which is an optional field that + // can be set to delay the spending of the output relative to the block + // height at which the output is confirmed. uint64 relative_lock_time = 10; // The delivery status of the proof associated with this output. ProofDeliveryStatus proof_delivery_status = 11; + // The asset ID of the asset that was created in this output. bytes asset_id = 12; + + // The proof courier address that was used to deliver the proof for this + // output. + string proof_courier_addr = 13; + + // The Taproot Asset address that was used to create the output. This is + // only set for new outputs for tapd versions that support the address V2 + // format. For older versions, this field will be empty. + string tap_addr = 14; } message StopRequest { @@ -897,9 +999,16 @@ message DebugLevelRequest { // If true, all the valid debug sub-systems will be returned. bool show = 1; + // If set, the debug level for the sub-system will be set to this value. + // Can be one of: "trace", "debug", "info", "warn", "error", "critical", + // "off", to set a global level, optionally followed by a comma-separated + // list of sub-systems to set the level for. For example: + // "debug,TADB=info,UNIV=warn". string level_spec = 2; } message DebugLevelResponse { + // The list of available logging sub-systems that can be set to a specific + // debug level. string sub_systems = 1; } @@ -914,22 +1023,33 @@ enum AddrVersion { // ADDR_VERSION_V1 is the address version that uses V2 Taproot Asset // commitments. ADDR_VERSION_V1 = 2; + + // ADDR_VERSION_V2 is the address version that supports sending grouped + // assets and require the new auth mailbox proof courier address format. + ADDR_VERSION_V2 = 3; } message Addr { // The bech32 encoded Taproot Asset address. string encoded = 1; - // The asset ID that uniquely identifies the asset. + // The asset ID that uniquely identifies the asset. This can be all zeroes + // for V2 addresses that have a group key set. bytes asset_id = 2; // The type of the asset. AssetType asset_type = 3; - // The total amount of the asset stored in this Taproot Asset UTXO. + // The total amount of the asset stored in this Taproot Asset UTXO. The + // amount is allowed to be unset for V2 addresses, where the sender will + // post a fragment containing the asset IDs and amounts to the proof + // courier's auth mailbox. uint64 amount = 4; - // The group key of the asset (if it exists) + // The group key of the asset group to receive assets for. If this field + // is set, then any asset of the group can be sent to this address. Can only + // be specified for V2 addresses. If this field is set, the asset_id + // field must be empty. bytes group_key = 5; /* @@ -956,7 +1076,9 @@ message Addr { */ bytes taproot_output_key = 9; - // The address of the proof courier service used in proof transfer. + // The address of the proof courier service used in proof transfer. For V2 + // addresses the proof courier address is mandatory and must be a valid auth + // mailbox address (authmailbox+universerpc://host:port). string proof_courier_addr = 10; // The asset version of the address. @@ -987,12 +1109,23 @@ message QueryAddrRequest { } message QueryAddrResponse { + // The list of addresses that match the query parameters. repeated Addr addrs = 1; } message NewAddrRequest { + /* + The asset ID to create the address for. This is required for V0 and V1 + addresses. For V2 addresses, this field is optional and must be empty if the + group key is set. + */ bytes asset_id = 1; + /* + The number of asset units to be sent to the address. This is required for V0 + and V1 addresses. For V2 addresses, this field is optional and can be left + at 0 to indicate that the sender can choose the amount of assets to send. + */ uint64 amt = 2; /* @@ -1038,13 +1171,26 @@ message NewAddrRequest { The version of this address. */ AddrVersion address_version = 8; + + /* + The group key to receive assets for. This can only be specified for V2 + addresses. If this field is set, the asset_id field must be empty. + */ + bytes group_key = 9; + + /* + If set, the daemon skips the connectivity check to the proof courier service + when creating an address. Connection checks currently apply only to certain + address schemes. Use this to create addresses while offline. + */ + bool skip_proof_courier_conn_check = 10; } enum ScriptKeyType { /* The type of script key is not known. This should only be stored for assets - where we don't know the internal key of the script key (e.g. for - imported proofs). + where we don't know the internal key of the script key (e.g. for imported + proofs). */ SCRIPT_KEY_UNKNOWN = 0; @@ -1085,6 +1231,17 @@ enum ScriptKeyType { selection. */ SCRIPT_KEY_CHANNEL = 5; + + /* + The script key is derived using the asset ID and a single leaf that contains + an un-spendable Pedersen commitment key + `(OP_CHECKSIG )`. This can be used to create + unique script keys for each virtual packet in the fragment, to avoid proof + collisions in the universe, where the script keys should be spendable by + a hardware wallet that only supports miniscript policies for signing P2TR + outputs. + */ + SCRIPT_KEY_UNIQUE_PEDERSEN = 6; } message ScriptKeyTypeQuery { @@ -1174,6 +1331,7 @@ message TapBranch { } message DecodeAddrRequest { + // The bech32 encoded Taproot Asset address to decode. string addr = 1; } @@ -1182,6 +1340,8 @@ message ProofFile { // individual mint/transfer proof. bytes raw_proof_file = 1; + // The genesis point of the proof file, which is the asset's genesis + // transaction outpoint. string genesis_point = 2; } @@ -1250,6 +1410,7 @@ message DecodedProof { } message VerifyProofResponse { + // Whether the proof file was valid or not. bool valid = 1; // The decoded last proof in the file if the proof file was valid. @@ -1276,12 +1437,18 @@ message DecodeProofRequest { } message DecodeProofResponse { + // The decoded, more human-readable proof. DecodedProof decoded_proof = 1; } message ExportProofRequest { + // The asset ID of the asset to export the proof for. bytes asset_id = 1; + + // The script key of the asset to export the proof for. bytes script_key = 2; + + // The on-chain outpoint of the asset to export the proof for. OutPoint outpoint = 3; // TODO(roasbeef): specify information to make new state transition in proof @@ -1353,6 +1520,14 @@ message AddrReceivesRequest { // Filter receives by a specific status. Leave empty to get all receives. AddrEventStatus filter_status = 2; + + // Filter receives by creation time greater than or equal to this timestamp. + // If not set, no start time filtering is applied. + uint64 start_timestamp = 3; + + // Filter receives by creation time less than or equal to this timestamp. + // If not set, no end time filtering is applied. + uint64 end_timestamp = 4; } message AddrReceivesResponse { @@ -1361,12 +1536,17 @@ message AddrReceivesResponse { } message SendAssetRequest { + // The list of TAP addresses to send assets to. The amount to send to each + // address is determined by the amount specified in the address itself. For + // V2 addresses that are allowed to not specify an amount, use the + // addresses_with_amounts list to specify the amount to send to each + // address. The tap_addrs and addresses_with_amounts lists are mutually + // exclusive, meaning that if addresses_with_amounts is set, then tap_addrs + // must be empty, and vice versa. repeated string tap_addrs = 1; // The optional fee rate to use for the minting transaction, in sat/kw. uint32 fee_rate = 2; - // TODO(roasbeef): maybe in future add details re type of ProofCourier or - // w/e // An optional short label for the send transfer. This label can be used to // track the progress of the transfer via the logs or an event subscription. @@ -1377,16 +1557,45 @@ message SendAssetRequest { // testing purposes and for forced transfers when the proof courier // is not immediately available. bool skip_proof_courier_ping_check = 4; + + // A list of addresses and the amounts of asset units to send to them. This + // must be used for V2 TAP addresses that don't specify an amount in the + // address itself and allow the sender to choose the amount to send. The + // tap_addrs and addresses_with_amounts lists are mutually exclusive, + // meaning that if addresses_with_amounts is set, then tap_addrs must be + // empty, and vice versa. + repeated AddressWithAmount addresses_with_amounts = 5; +} + +message AddressWithAmount { + // The TAP address to send assets to. + string tap_addr = 1; + + // The amount of asset units to send to the address. This is only used for + // re-usable V2 addresses that don't specify an amount in the address itself + // and allow the sender to specify the amount on each send attempt. For V0 + // or V1 addresses, this can be left empty (zero) as the amount is taken + // from the address itself. + uint64 amount = 2; } message PrevInputAsset { + // The previous input's anchor point, which is the on-chain outpoint the + // asset was anchored to. string anchor_point = 1; + + // The asset ID of the asset that was spent as an input. bytes asset_id = 2; + + // The script key of the asset that was spent as an input. bytes script_key = 3; + + // The amount of the asset that was spent as an input. uint64 amount = 4; } message SendAssetResponse { + // The transfer that was created to send assets to one or more addresses. AssetTransfer transfer = 1; } @@ -1394,13 +1603,32 @@ message GetInfoRequest { } message GetInfoResponse { + // The full version string of the Taproot Asset daemon. string version = 1; + + // The full version string of the LND node that this daemon is connected to. string lnd_version = 2; + + // The network this daemon is connected to, e.g. "mainnet", "testnet", or + // any other supported network. string network = 3; + + // The public key of the LND node that this daemon is connected to. string lnd_identity_pubkey = 4; + + // The alias of the LND node that this daemon is connected to. string node_alias = 5; + + // The current block height as seen by the LND node this daemon is + // connected to. uint32 block_height = 6; + + // The current block hash as seen by the LND node this daemon is connected + // to. string block_hash = 7; + + // Whether the LND node this daemon is connected to is synced to the + // Bitcoin chain. bool sync_to_chain = 8; } @@ -1420,6 +1648,54 @@ message FetchAssetMetaRequest { } } +message FetchAssetMetaResponse { + /* + The raw data of the asset meta data. Based on the type below, this may be + structured data such as a text file or PDF. The size of the data is limited + to 1MiB. + */ + bytes data = 1; + + // The type of the asset meta data. + AssetMetaType type = 2; + + /* + The hash of the meta. This is the hash of the TLV serialization of the meta + itself. + */ + bytes meta_hash = 3; + + /* + A map of unknown odd TLV types that were encountered during asset meta data + decoding. + */ + map unknown_odd_types = 4; + + /* + The decimal display value of the asset. This is used to determine the number + of decimal places to display when presenting the asset amount to the user. + */ + uint32 decimal_display = 5; + + /* + Boolean flag indicating whether the asset-group issuer publishes + universe-supply commitments to the canonical universe set. + */ + bool universe_commitments = 6; + + /* + List of canonical universe URLs where the asset-group issuer publishes + asset-related proofs. + */ + repeated string canonical_universe_urls = 7; + + /* + The public key that is used to verify universe supply commitment related + on-chain outputs and proofs. + */ + bytes delegation_key = 8; +} + message BurnAssetRequest { oneof asset { // The asset ID of the asset to burn units of. @@ -1429,6 +1705,7 @@ message BurnAssetRequest { string asset_id_str = 2; } + // The number of asset units to burn. This must be greater than zero. uint64 amount_to_burn = 3; // A safety check to ensure the user is aware of the destructive nature of @@ -1477,21 +1754,10 @@ message AssetBurn { } message ListBurnsResponse { + // The list of asset burns that match the query parameters. repeated AssetBurn burns = 1; } -message OutPoint { - /* - Raw bytes representing the transaction id. - */ - bytes txid = 1; - - /* - The index of the output on the transaction. - */ - uint32 output_index = 2; -} - message SubscribeReceiveEventsRequest { // Filter receives by a specific address. Leave empty to get all receive // events for all addresses. @@ -1533,6 +1799,10 @@ message SubscribeSendEventsRequest { // Filter send events by a specific label. Leave empty to not filter by // transfer label. string filter_label = 2; + + // 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 = 3; } enum SendState { @@ -1636,6 +1906,8 @@ message SendEvent { } message AnchorTransaction { + // The on-chain anchor transaction PSBT packet that was created by the + // daemon. bytes anchor_psbt = 1; /* @@ -1682,5 +1954,6 @@ message RegisterTransferRequest { } message RegisterTransferResponse { + // The asset transfer that was registered. Asset registered_asset = 1; } diff --git a/protos/tapd/v0.6.0/universerpc/universe.proto b/protos/tapd/v0.7.0/universerpc/universe.proto similarity index 55% rename from protos/tapd/v0.6.0/universerpc/universe.proto rename to protos/tapd/v0.7.0/universerpc/universe.proto index e27da19..bfe4143 100644 --- a/protos/tapd/v0.6.0/universerpc/universe.proto +++ b/protos/tapd/v0.7.0/universerpc/universe.proto @@ -1,5 +1,6 @@ syntax = "proto3"; +import "tapcommon.proto"; import "taprootassets.proto"; package universerpc; @@ -82,7 +83,9 @@ service Universe { // TODO(roasbeef): rename resp to UniverseStateUpdate? ^ /* tapcli: `universe info` - Info returns a set of information about the current state of the Universe. + Info returns a set of information about the current state of the Universe + and allows a caller to check that a universe server is reachable and + configured correctly to allow proof courier access without macaroons. */ rpc Info (InfoRequest) returns (InfoResponse); @@ -154,6 +157,44 @@ service Universe { */ rpc QueryFederationSyncConfig (QueryFederationSyncConfigRequest) returns (QueryFederationSyncConfigResponse); + + /* tapcli: `universe ignoreoutpoint` + IgnoreAssetOutPoint allows an asset issuer to mark a specific asset outpoint + as ignored. An ignored outpoint will be included in the next universe supply + commitment transaction that is published. + */ + rpc IgnoreAssetOutPoint (IgnoreAssetOutPointRequest) + returns (IgnoreAssetOutPointResponse); + + /* tapcli: `universe updatesupplycommit` + UpdateSupplyCommit updates the on-chain supply commitment for a specific + asset group. + */ + rpc UpdateSupplyCommit (UpdateSupplyCommitRequest) + returns (UpdateSupplyCommitResponse); + + /* tapcli: `universe fetchsupplycommit` + FetchSupplyCommit fetches the on-chain supply commitment for a specific + asset group. + */ + rpc FetchSupplyCommit (FetchSupplyCommitRequest) + returns (FetchSupplyCommitResponse); + + /* tapcli: `universe supplyleaves` + FetchSupplyLeaves fetches the supply leaves for a specific asset group + within a specified block height range. The leaves include issuance, burn, + and ignore leaves, which represent the supply changes for the asset group. + */ + rpc FetchSupplyLeaves (FetchSupplyLeavesRequest) + returns (FetchSupplyLeavesResponse); + + /* tapcli: `universe supplycommit insert` + InsertSupplyCommit inserts a supply commitment for a specific asset + group. This includes the commitment details, supply leaves (issuance, burn, + and ignore), and chain proof that proves the commitment has been mined. + */ + rpc InsertSupplyCommit (InsertSupplyCommitRequest) + returns (InsertSupplyCommitResponse); } message MultiverseRootRequest { @@ -228,6 +269,7 @@ message ID { } message UniverseRoot { + // The ID of the asset universe root. ID id = 1; // The merkle sum sparse merkle tree root associated with the above @@ -428,6 +470,7 @@ enum UniverseSyncMode { } message SyncTarget { + // The ID of the asset to sync. ID id = 1; } @@ -464,7 +507,12 @@ message SyncResponse { } message UniverseFederationServer { + // The host of the federation server, which is used to connect to the + // server to push proofs and sync new proofs. string host = 1; + + // The numeric ID of the federation server. This is used to identify + // existing servers when adding or deleting them from the federation. int32 id = 2; } @@ -472,10 +520,13 @@ message ListFederationServersRequest { } message ListFederationServersResponse { + // The list of federation servers that make up the local Universe + // federation. repeated UniverseFederationServer servers = 1; } message AddFederationServerRequest { + // The federation server to add to the local Universe federation. repeated UniverseFederationServer servers = 1; } @@ -483,6 +534,7 @@ message AddFederationServerResponse { } message DeleteFederationServerRequest { + // The federation server to delete from the local Universe federation. repeated UniverseFederationServer servers = 1; } @@ -529,18 +581,31 @@ enum AssetTypeFilter { } message AssetStatsQuery { + // The asset name filter. If this is empty, then all assets are returned. string asset_name_filter = 1; + // The asset ID filter. If this is empty, then all assets are returned. bytes asset_id_filter = 2; + // The asset type filter. If this is set to FILTER_ASSET_NONE, then all + // assets are returned. If set to FILTER_ASSET_NORMAL, then only normal + // assets are returned. If set to FILTER_ASSET_COLLECTIBLE, then only + // collectible assets are returned. AssetTypeFilter asset_type_filter = 3; + // The sort order for the query. If this is set to SORT_BY_NONE, then the + // results are not sorted. AssetQuerySort sort_by = 4; + // The offset for the page. This is used for pagination. int32 offset = 5; + // The length limit for the page. This is used for pagination. int32 limit = 6; + // The direction of the sort. If this is set to SORT_DIRECTION_ASC, then + // the results are sorted in ascending order. If set to + // SORT_DIRECTION_DESC, then the results are sorted in descending order. SortDirection direction = 7; } @@ -571,48 +636,76 @@ message AssetStatsSnapshot { } message AssetStatsAsset { + // The ID of the asset. bytes asset_id = 1; + // The asset's genesis point, which is the outpoint of the genesis + // transaction that created the asset. This is a hex encoded string. string genesis_point = 2; + // The total supply of the asset. This is the total number of units of the + // asset that have been issued. int64 total_supply = 3; + // The human-readable name of the asset. string asset_name = 4; + // The type of the asset. This can be either a normal asset or a collectible + // asset. taprpc.AssetType asset_type = 5; + // The height of the block at which the asset was created. int32 genesis_height = 6; + // The timestamp of the block at which the asset was created, in Unix epoch + // time (seconds). int64 genesis_timestamp = 7; + // The anchor point of the asset, which is a human-readable string that + // represents the asset's anchor point in the blockchain. string anchor_point = 8; + // The decimal display value for the asset. This is the number of decimal + // places that the asset can be divided into. uint32 decimal_display = 9; } message UniverseAssetStats { + // The asset statistics snapshot for the queried assets. repeated AssetStatsSnapshot asset_stats = 1; } message QueryEventsRequest { + // The start timestamp for the query, in Unix epoch time (seconds). int64 start_timestamp = 1; + + // The end timestamp for the query, in Unix epoch time (seconds). int64 end_timestamp = 2; } message QueryEventsResponse { + // The list of grouped universe events that occurred within the specified + // time range. Each entry in the list represents a day, with the number of + // sync and new proof events that occurred on that day. repeated GroupedUniverseEvents events = 1; } message GroupedUniverseEvents { // The date the events occurred on, formatted as YYYY-MM-DD. string date = 1; + + // The number of sync events that occurred on this date. uint64 sync_events = 2; + + // The number of new proof events that occurred on this date. uint64 new_proof_events = 3; } message SetFederationSyncConfigRequest { + // The global federation sync configs for the given proof types. repeated GlobalFederationSyncConfig global_sync_configs = 1; + // The asset federation sync configs for the given universe IDs. repeated AssetFederationSyncConfig asset_sync_configs = 2; } @@ -659,7 +752,312 @@ message QueryFederationSyncConfigRequest { } message QueryFederationSyncConfigResponse { + // The global federation sync configs for the given proof types. repeated GlobalFederationSyncConfig global_sync_configs = 1; + // The asset federation sync configs for the given universe IDs. repeated AssetFederationSyncConfig asset_sync_configs = 2; } + +message IgnoreAssetOutPointRequest { + // The outpoint of the asset to ignore. + taprpc.AssetOutPoint asset_out_point = 1; + + // The amount of asset units at the associated asset outpoint. + uint64 amount = 2; +} + +message IgnoreAssetOutPointResponse { + // The key identifying the signed ignore outpoint leaf in the ignore supply + // commitment subtree. + bytes leaf_key = 1; + + // The signed ignore outpoint leaf in the ignore supply commitment tree. + MerkleSumNode leaf = 2; +} + +message UpdateSupplyCommitRequest { + // The unique identifier for the target asset group whose supply commitment + // is being updated. + oneof group_key { + // The 32-byte asset group key specified as raw bytes (gRPC only). + bytes group_key_bytes = 1; + + // The 32-byte asset group key encoded as hex string (use this for + // REST). + string group_key_str = 2; + } +} + +message UpdateSupplyCommitResponse { +} + +message FetchSupplyCommitRequest { + // The unique identifier for the target asset group whose supply commitment + // is being fetched. + oneof group_key { + // The 32-byte asset group key specified as raw bytes (gRPC only). + bytes group_key_bytes = 1; + + // The 32-byte asset group key encoded as hex string (use this for + // REST). + string group_key_str = 2; + } + + // Specifies which supply commit to fetch. + oneof locator { + // Fetch the the supply commitment that created this new commitment + // output on chain. + taprpc.OutPoint commit_outpoint = 3; + + // Fetch the supply commitment that spent the specified commitment + // output on chain to create a new supply commitment. This can be used + // to traverse the chain of supply commitments by watching the spend of + // the commitment output. + taprpc.OutPoint spent_commit_outpoint = 4; + + // Fetch the very first supply commitment for the asset group. This + // returns the initial supply commitment that spent the pre-commitment + // output of the very first asset mint of a grouped asset (also known + // as the group anchor). This is useful as the starting point to fetch + // all supply commitments for a grouped asset one by one. + bool very_first = 5; + + // Fetch the latest supply commitment for the asset group. This returns + // the most recent supply commitment that is anchored on chain for the + // asset group. This is useful to always get the current supply state + // of the asset group. + bool latest = 6; + } +} + +message SupplyCommitSubtreeRoot { + // The type of the supply commit subtree. + string type = 1; + + // The root node of the supply commit subtree. + MerkleSumNode root_node = 2; + + // The leaf key which locates the subtree leaf node in the supply commit + // tree. + bytes supply_tree_leaf_key = 3; + + // The inclusion proof for the supply commit subtree root node. + bytes supply_tree_inclusion_proof = 4; +} + +message FetchSupplyCommitResponse { + // The supply commitment chain data that contains both the commitment and + // chain proof information. + SupplyCommitChainData chain_data = 1; + + // The total number of satoshis in on-chain fees paid by the supply + // commitment transaction. + int64 tx_chain_fees_sats = 2; + + // The root of the issuance tree for the specified asset. + SupplyCommitSubtreeRoot issuance_subtree_root = 3; + + // The root of the burn tree for the specified asset. + SupplyCommitSubtreeRoot burn_subtree_root = 4; + + // The root of the ignore tree for the specified asset. + SupplyCommitSubtreeRoot ignore_subtree_root = 5; + + // The issuance leaves that were added by this supply commitment. Does not + // include leaves that were already present in the issuance subtree before + // the block height at which this supply commitment was anchored. + repeated SupplyLeafEntry issuance_leaves = 6; + + // The burn leaves that were added by this supply commitment. Does not + // include leaves that were already present in the burn subtree before + // the block height at which this supply commitment was anchored. + repeated SupplyLeafEntry burn_leaves = 7; + + // The ignore leaves that were added by this supply commitment. Does not + // include leaves that were already present in the ignore subtree before + // the block height at which this supply commitment was anchored. + repeated SupplyLeafEntry ignore_leaves = 8; + + // The total outstanding supply of the asset after applying all the supply + // changes (issuance, burn, ignore) included in this supply commitment. + uint64 total_outstanding_supply = 9; + + // The outpoint of the previous commitment that this new commitment is + // spending. This must be set unless this is the very first supply + // commitment of a grouped asset. + taprpc.OutPoint spent_commitment_outpoint = 10; + + // A map of block height to supply leaf block header for all block heights + // referenced in supply leaves. + map block_headers = 11; +} + +message FetchSupplyLeavesRequest { + // The unique identifier for the target asset group whose supply leaves are + // being fetched. + oneof group_key { + // The 32-byte asset group key specified as raw bytes (gRPC only). + bytes group_key_bytes = 1; + + // The 32-byte asset group key encoded as hex string (use this for + // REST). + string group_key_str = 2; + } + + // The start block height for the range of supply leaves to fetch. + uint32 block_height_start = 3; + + // The end block height for the range of supply leaves to fetch. + uint32 block_height_end = 4; + + // Optional: A list of issuance leaf keys. For each key in this list, + // the endpoint will generate and return an inclusion proof. + repeated bytes issuance_leaf_keys = 5; + + // Optional: A list of burn leaf keys. For each key in this list, + // the endpoint will generate and return an inclusion proof. + repeated bytes burn_leaf_keys = 6; + + // Optional: A list of ignore leaf keys. For each key in this list, the + // endpoint will generate and return an inclusion proof. + repeated bytes ignore_leaf_keys = 7; +} + +// SupplyLeafKey identifies a supply leaf entry. It contains the components +// used to derive the key, which is computed as a hash of these fields. +message SupplyLeafKey { + // The outpoint associated with the supply leaf. + Outpoint outpoint = 1; + + // The script key of the supply leaf. This is the script key of the asset + // point. + bytes script_key = 2; + + // The asset ID associated with the supply leaf. This is only set for + // ignore type supply leaves. + bytes asset_id = 3; +} + +message SupplyLeafEntry { + // The key that identifies the supply leaf in the supply commitment subtree. + SupplyLeafKey leaf_key = 1; + + // The merkle sum node representing the supply leaf in the supply commitment + // subtree. + MerkleSumNode leaf_node = 2; + + // The block height at which the supply leaf was created. + uint32 block_height = 3; + + // The raw serialized bytes of the supply leaf. + bytes raw_leaf = 4; +} + +message SupplyLeafBlockHeader { + // Block header timestamp in seconds since unix epoch. + int64 timestamp = 1; + + // 32-byte block header hash. + bytes hash = 2; +} + +message FetchSupplyLeavesResponse { + repeated SupplyLeafEntry issuance_leaves = 1; + repeated SupplyLeafEntry burn_leaves = 2; + repeated SupplyLeafEntry ignore_leaves = 3; + + // Inclusion proofs for each issuance leaf key provided in the request. + // Each entry corresponds to the key at the same index in + // `issuance_leaf_keys`. + repeated bytes issuance_leaf_inclusion_proofs = 4; + + // Inclusion proofs for each burn leaf key provided in the request. + // Each entry corresponds to the key at the same index in `burn_leaf_keys`. + repeated bytes burn_leaf_inclusion_proofs = 5; + + // Inclusion proofs for each ignored leaf key provided in the request. + // Each entry corresponds to the key at the same index in + // `ignore_leaf_keys`. + repeated bytes ignore_leaf_inclusion_proofs = 6; + + // A map of block height to supply leaf block header for all block heights + // referenced in supply leaves. + map block_headers = 7; +} + +// SupplyCommitChainData represents the on-chain artifacts for a supply +// commitment update. +message SupplyCommitChainData { + // The raw transaction that created the root commitment. + bytes txn = 1; + + // The index of the output in the transaction where the commitment resides. + uint32 tx_out_idx = 2; + + // The internal key used to create the commitment output. + bytes internal_key = 3; + + // The taproot output key used to create the commitment output. + bytes output_key = 4; + + // The root hash of the supply tree that contains the set of + // sub-commitments. The sum value of this tree is the outstanding supply + // value. + bytes supply_root_hash = 5; + + // The sum value of the supply root tree, representing the outstanding + // supply amount. + uint64 supply_root_sum = 6; + + // The block header of the block that contains the supply commitment + // transaction. + bytes block_header = 7; + + // The hash of the block that contains the commitment. + bytes block_hash = 8; + + // The block height of the block that contains the supply commitment + // transaction. + uint32 block_height = 9; + + // The merkle proof that proves that the supply commitment transaction is + // included in the block. + bytes tx_block_merkle_proof = 10; + + // The index of the supply commitment transaction in the block. + uint32 tx_index = 11; + + // The outpoint in the transaction where the commitment resides. + string commit_outpoint = 12; +} + +message InsertSupplyCommitRequest { + // The unique identifier for the target asset group whose supply commitment + // is being inserted. + oneof group_key { + // The 32-byte asset group key specified as raw bytes (gRPC only). + bytes group_key_bytes = 1; + + // The 32-byte asset group key encoded as hex string (use this for + // REST). + string group_key_str = 2; + } + + // The supply commitment chain data that contains both the commitment and + // chain proof information. + SupplyCommitChainData chain_data = 3; + + // The outpoint of the previous commitment that this new commitment is + // spending. This must be set unless this is the very first supply + // commitment of a grouped asset. + taprpc.OutPoint spent_commitment_outpoint = 4; + + // The supply leaves that represent the supply changes for the asset group. + repeated SupplyLeafEntry issuance_leaves = 5; + repeated SupplyLeafEntry burn_leaves = 6; + repeated SupplyLeafEntry ignore_leaves = 7; +} + +message InsertSupplyCommitResponse { +} \ No newline at end of file diff --git a/scripts/generate_types.sh b/scripts/generate_types.sh index a058726..bd2074a 100644 --- a/scripts/generate_types.sh +++ b/scripts/generate_types.sh @@ -74,7 +74,9 @@ protoc/bin/protoc \ signrpc/signer.proto \ walletrpc/walletkit.proto \ watchtowerrpc/watchtower.proto \ - wtclientrpc/wtclient.proto + wtclientrpc/wtclient.proto \ + peersrpc/peers.proto \ + stateservice.proto echo "LOOP: running protoc..." @@ -116,6 +118,7 @@ protoc/bin/protoc \ --plugin=./node_modules/.bin/protoc-gen-ts_proto \ --ts_proto_out=$GENERATED_TYPES_DIR/tapd \ $TS_PROTO_OPTIONS \ + tapcommon.proto \ taprootassets.proto \ assetwalletrpc/assetwallet.proto \ mintrpc/mint.proto \ @@ -123,7 +126,8 @@ protoc/bin/protoc \ rfqrpc/rfq.proto \ tapchannelrpc/tapchannel.proto \ tapdevrpc/tapdev.proto \ - universerpc/universe.proto + universerpc/universe.proto \ + authmailboxrpc/mailbox.proto echo "LiT: running protoc..." mkdir -p "$GENERATED_TYPES_DIR/lit" @@ -169,7 +173,9 @@ protoc/bin/protoc \ signrpc/signer.proto \ walletrpc/walletkit.proto \ watchtowerrpc/watchtower.proto \ - wtclientrpc/wtclient.proto + wtclientrpc/wtclient.proto \ + peersrpc/peers.proto \ + stateservice.proto echo "LOOP: generating schema..." mkdir -p "$SCHEMA_DIR/loop" @@ -210,6 +216,7 @@ protoc/bin/protoc \ --plugin=./node_modules/.bin/protoc-gen-ts_proto \ --ts_proto_out=$SCHEMA_DIR/tapd \ $SCHEMA_PROTO_OPTIONS \ + tapcommon.proto \ taprootassets.proto \ assetwalletrpc/assetwallet.proto \ mintrpc/mint.proto \ @@ -217,7 +224,8 @@ protoc/bin/protoc \ rfqrpc/rfq.proto \ tapchannelrpc/tapchannel.proto \ tapdevrpc/tapdev.proto \ - universerpc/universe.proto + universerpc/universe.proto \ + authmailboxrpc/mailbox.proto echo "LIT: generating schema..." mkdir -p "$SCHEMA_DIR/lit" diff --git a/scripts/update_protos.sh b/scripts/update_protos.sh index 5b3572f..8739087 100644 --- a/scripts/update_protos.sh +++ b/scripts/update_protos.sh @@ -34,6 +34,8 @@ curl ${LND_URL}/${LND_RELEASE_TAG}/lnrpc/signrpc/signer.proto --create-dirs -o p curl ${LND_URL}/${LND_RELEASE_TAG}/lnrpc/walletrpc/walletkit.proto --create-dirs -o protos/lnd/${LND_RELEASE_TAG}/walletrpc/walletkit.proto curl ${LND_URL}/${LND_RELEASE_TAG}/lnrpc/watchtowerrpc/watchtower.proto --create-dirs -o protos/lnd/${LND_RELEASE_TAG}/watchtowerrpc/watchtower.proto curl ${LND_URL}/${LND_RELEASE_TAG}/lnrpc/wtclientrpc/wtclient.proto --create-dirs -o protos/lnd/${LND_RELEASE_TAG}/wtclientrpc/wtclient.proto +curl ${LND_URL}/${LND_RELEASE_TAG}/lnrpc/peersrpc/peers.proto --create-dirs -o protos/lnd/${LND_RELEASE_TAG}/peersrpc/peers.proto +curl ${LND_URL}/${LND_RELEASE_TAG}/lnrpc/stateservice.proto --create-dirs -o protos/lnd/${LND_RELEASE_TAG}/stateservice.proto curl ${LOOP_URL}/${LOOP_RELEASE_TAG}/looprpc/client.proto --create-dirs -o protos/loop/${LOOP_RELEASE_TAG}/client.proto curl ${LOOP_URL}/${LOOP_RELEASE_TAG}/looprpc/debug.proto --create-dirs -o protos/loop/${LOOP_RELEASE_TAG}/debug.proto @@ -46,6 +48,7 @@ curl ${POOL_URL}/${POOL_RELEASE_TAG}/auctioneerrpc/hashmail.proto --create-dirs curl ${FARADAY_URL}/${FARADAY_RELEASE_TAG}/frdrpc/faraday.proto --create-dirs -o protos/faraday/${FARADAY_RELEASE_TAG}/faraday.proto +curl ${TAPD_URL}/${TAPD_RELEASE_TAG}/taprpc/tapcommon.proto --create-dirs -o protos/tapd/${TAPD_RELEASE_TAG}/tapcommon.proto 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 @@ -54,6 +57,7 @@ curl ${TAPD_URL}/${TAPD_RELEASE_TAG}/taprpc/rfqrpc/rfq.proto --create-dirs -o pr 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 ${TAPD_URL}/${TAPD_RELEASE_TAG}/taprpc/authmailboxrpc/mailbox.proto --create-dirs -o protos/tapd/${TAPD_RELEASE_TAG}/authmailboxrpc/mailbox.proto curl ${LIT_URL}/${LIT_RELEASE_TAG}/litrpc/firewall.proto --create-dirs -o protos/lit/${LIT_RELEASE_TAG}/firewall.proto curl ${LIT_URL}/${LIT_RELEASE_TAG}/litrpc/lit-sessions.proto --create-dirs -o protos/lit/${LIT_RELEASE_TAG}/lit-sessions.proto