Skip to content

Commit 10a7228

Browse files
committed
Docs improvements for channel
1 parent 2d213a4 commit 10a7228

File tree

1 file changed

+30
-26
lines changed

1 file changed

+30
-26
lines changed

lightning/src/ln/channel.rs

+30-26
Original file line numberDiff line numberDiff line change
@@ -245,52 +245,52 @@ enum HTLCUpdateAwaitingACK {
245245
}
246246

247247
/// There are a few "states" and then a number of flags which can be applied:
248-
/// We first move through init with OurInitSent -> TheirInitSent -> FundingCreated -> FundingSent.
249-
/// TheirChannelReady and OurChannelReady then get set on FundingSent, and when both are set we
250-
/// move on to ChannelReady.
251-
/// Note that PeerDisconnected can be set on both ChannelReady and FundingSent.
252-
/// ChannelReady can then get all remaining flags set on it, until we finish shutdown, then we
253-
/// move on to ShutdownComplete, at which point most calls into this channel are disallowed.
248+
/// We first move through init with `OurInitSent` -> `TheirInitSent` -> `FundingCreated` -> `FundingSent`.
249+
/// `TheirChannelReady` and `OurChannelReady` then get set on `FundingSent`, and when both are set we
250+
/// move on to `ChannelReady`.
251+
/// Note that `PeerDisconnected` can be set on both `ChannelReady` and `FundingSent`.
252+
/// `ChannelReady` can then get all remaining flags set on it, until we finish shutdown, then we
253+
/// move on to `ShutdownComplete`, at which point most calls into this channel are disallowed.
254254
enum ChannelState {
255255
/// Implies we have (or are prepared to) send our open_channel/accept_channel message
256256
OurInitSent = 1 << 0,
257-
/// Implies we have received their open_channel/accept_channel message
257+
/// Implies we have received their `open_channel`/`accept_channel` message
258258
TheirInitSent = 1 << 1,
259-
/// We have sent funding_created and are awaiting a funding_signed to advance to FundingSent.
260-
/// Note that this is nonsense for an inbound channel as we immediately generate funding_signed
261-
/// upon receipt of funding_created, so simply skip this state.
259+
/// We have sent `funding_created` and are awaiting a `funding_signed` to advance to `FundingSent`.
260+
/// Note that this is nonsense for an inbound channel as we immediately generate `funding_signed`
261+
/// upon receipt of `funding_created`, so simply skip this state.
262262
FundingCreated = 4,
263-
/// Set when we have received/sent funding_created and funding_signed and are thus now waiting
264-
/// on the funding transaction to confirm. The ChannelReady flags are set to indicate when we
263+
/// Set when we have received/sent `funding_created` and `funding_signed` and are thus now waiting
264+
/// on the funding transaction to confirm. The `ChannelReady` flags are set to indicate when we
265265
/// and our counterparty consider the funding transaction confirmed.
266266
FundingSent = 8,
267-
/// Flag which can be set on FundingSent to indicate they sent us a channel_ready message.
268-
/// Once both TheirChannelReady and OurChannelReady are set, state moves on to ChannelReady.
267+
/// Flag which can be set on `FundingSent` to indicate they sent us a `channel_ready` message.
268+
/// Once both `TheirChannelReady` and `OurChannelReady` are set, state moves on to `ChannelReady`.
269269
TheirChannelReady = 1 << 4,
270-
/// Flag which can be set on FundingSent to indicate we sent them a channel_ready message.
271-
/// Once both TheirChannelReady and OurChannelReady are set, state moves on to ChannelReady.
270+
/// Flag which can be set on `FundingSent` to indicate we sent them a `channel_ready` message.
271+
/// Once both `TheirChannelReady` and `OurChannelReady` are set, state moves on to `ChannelReady`.
272272
OurChannelReady = 1 << 5,
273273
ChannelReady = 64,
274-
/// Flag which is set on ChannelReady and FundingSent indicating remote side is considered
275-
/// "disconnected" and no updates are allowed until after we've done a channel_reestablish
274+
/// Flag which is set on `ChannelReady` and `FundingSent` indicating remote side is considered
275+
/// "disconnected" and no updates are allowed until after we've done a `channel_reestablish`
276276
/// dance.
277277
PeerDisconnected = 1 << 7,
278-
/// Flag which is set on ChannelReady, FundingCreated, and FundingSent indicating the user has
279-
/// told us a ChannelMonitor update is pending async persistence somewhere and we should pause
278+
/// Flag which is set on `ChannelReady`, FundingCreated, and `FundingSent` indicating the user has
279+
/// told us a `ChannelMonitor` update is pending async persistence somewhere and we should pause
280280
/// sending any outbound messages until they've managed to finish.
281281
MonitorUpdateInProgress = 1 << 8,
282282
/// Flag which implies that we have sent a commitment_signed but are awaiting the responding
283283
/// revoke_and_ack message. During this time period, we can't generate new commitment_signed
284284
/// messages as then we will be unable to determine which HTLCs they included in their
285285
/// revoke_and_ack implicit ACK, so instead we have to hold them away temporarily to be sent
286286
/// later.
287-
/// Flag is set on ChannelReady.
287+
/// Flag is set on `ChannelReady`.
288288
AwaitingRemoteRevoke = 1 << 9,
289-
/// Flag which is set on ChannelReady or FundingSent after receiving a shutdown message from
289+
/// Flag which is set on `ChannelReady` or `FundingSent` after receiving a shutdown message from
290290
/// the remote end. If set, they may not add any new HTLCs to the channel, and we are expected
291291
/// to respond with our own shutdown message when possible.
292292
RemoteShutdownSent = 1 << 10,
293-
/// Flag which is set on ChannelReady or FundingSent after sending a shutdown message. At this
293+
/// Flag which is set on `ChannelReady` or `FundingSent` after sending a shutdown message. At this
294294
/// point, we may not add any new HTLCs to the channel.
295295
LocalShutdownSent = 1 << 11,
296296
/// We've successfully negotiated a closing_signed dance. At this point ChannelManager is about
@@ -4565,9 +4565,11 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
45654565
&self.channel_type
45664566
}
45674567

4568-
/// Guaranteed to be Some after both ChannelReady messages have been exchanged (and, thus,
4569-
/// is_usable() returns true).
4568+
/// Guaranteed to be [`Some`] after both [`ChannelState::ChannelReady`] messages have been exchanged
4569+
/// (and, thus, [`is_usable()`] returns true).
45704570
/// Allowed in any state (including after shutdown)
4571+
///
4572+
/// [`is_usable()`]: Self::is_usable
45714573
pub fn get_short_channel_id(&self) -> Option<u64> {
45724574
self.short_channel_id
45734575
}
@@ -5401,14 +5403,16 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
54015403
}
54025404

54035405
/// Gets an UnsignedChannelAnnouncement for this channel. The channel must be publicly
5404-
/// announceable and available for use (have exchanged ChannelReady messages in both
5406+
/// announceable and available for use (have exchanged [`ChannelReady`] messages in both
54055407
/// directions). Should be used for both broadcasted announcements and in response to an
54065408
/// AnnouncementSignatures message from the remote peer.
54075409
///
54085410
/// Will only fail if we're not in a state where channel_announcement may be sent (including
54095411
/// closing).
54105412
///
54115413
/// This will only return ChannelError::Ignore upon failure.
5414+
///
5415+
/// [`ChannelReady`]: crate::ln::msgs::ChannelReady
54125416
fn get_channel_announcement<NS: Deref>(
54135417
&self, node_signer: &NS, chain_hash: BlockHash, user_config: &UserConfig,
54145418
) -> Result<msgs::UnsignedChannelAnnouncement, ChannelError> where NS::Target: NodeSigner {

0 commit comments

Comments
 (0)