docs: expand concept docs and add comprehensive troubleshooting guide#74
Open
HappySonnyDev wants to merge 1 commit into
Open
docs: expand concept docs and add comprehensive troubleshooting guide#74HappySonnyDev wants to merge 1 commit into
HappySonnyDev wants to merge 1 commit into
Conversation
HappySonnyDev
commented
Jun 15, 2026
HappySonnyDev
commented
Collaborator
- Expand unidirectional-channel.mdx with relay node setup, liquidity management, and payment flow details
- Expand hold-invoice.mdx with full lifecycle, trust model, and settlement scenarios
- Expand invoice-guide.mdx with creation parameters, payment flow, and status tracking
- Expand payment-lifecycle.mdx with session/attempt model, fee budgeting, and error handling
- Expand multi-hop.mdx with relay node operation, routing algorithm, and retry behavior
- Expand trampoline-routing.mdx with two-level onion, feature negotiation, and constraints
- Add payment, channel, invoice, and trampoline error sections to troubleshooting.mdx
- Add TLC glossary entry and update glossary link path
- Expand unidirectional-channel.mdx with relay node setup, liquidity management, and payment flow details - Expand hold-invoice.mdx with full lifecycle, trust model, and settlement scenarios - Expand invoice-guide.mdx with creation parameters, payment flow, and status tracking - Expand payment-lifecycle.mdx with session/attempt model, fee budgeting, and error handling - Expand multi-hop.mdx with relay node operation, routing algorithm, and retry behavior - Expand trampoline-routing.mdx with two-level onion, feature negotiation, and constraints - Add payment, channel, invoice, and trampoline error sections to troubleshooting.mdx - Add TLC glossary entry and update glossary link path
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
yfeng2824
reviewed
Jun 16, 2026
|
|
||
| Or using `fnn-cli`: | ||
| <Callout> | ||
| The `funding_amount` is in **shannons** (1 CKB = 10⁸ shannons). By default, 99 CKB is reserved for the channel reserve (98 CKB minimum cell capacity + 1 CKB default shutdown fee), so the available balance for payments is `funding_amount - 99_00000000` shannons. This default can be adjusted via the `FIBER_AUTO_ACCEPT_CHANNEL_CKB_FUNDING_AMOUNT` environment variable. |
Collaborator
There was a problem hiding this comment.
The FIBER_AUTO_ACCEPT_CHANNEL_CKB_FUNDING_AMOUNT env var controls the auto-accept funding contribution, not the channel reserve itself.
yfeng2824
reviewed
Jun 16, 2026
| "is_public": false, | ||
| "is_one_way": true, | ||
| "is_acceptor": false, | ||
| "state": { "state_name": "CHANNEL_READY" }, |
Collaborator
There was a problem hiding this comment.
Suggested change
| "state": { "state_name": "CHANNEL_READY" }, | |
| "state": { "state_name": "ChannelReady" }, |
yfeng2824
reviewed
Jun 16, 2026
| | # | Field | Required | Size | Description | | ||
| |---|-------|----------|------|-------------| | ||
| | 1 | `timestamp` | Yes | 128 bits | Milliseconds since the UNIX epoch | | ||
| | 2 | `payment_hash` | Yes | 256 bits | Unique identifier of the invoice. Derived from `blake2b_256(preimage)` for hold invoices, or randomly generated for AMP invoices | |
Collaborator
There was a problem hiding this comment.
Should we specify that when neither payment_preimage nor payment_hash is supplied, Fiber generates a random preimage for a regular invoice; for hold invoices, the caller supplies payment_hash; the hash algorithm is ckb_hash by default unless sha256 is set?
yfeng2824
reviewed
Jun 16, 2026
| | `TemporaryChannelFailure` | A channel temporarily lacks liquidity (retryable) | | ||
|
|
||
| A PaymentAttempt represents a single routing attempt for a portion of the payment amount. A PaymentSession can have one or more attempts (for multi-path payments). | ||
| The `last_error` and `last_error_code` fields on the session provide the most recent failure reason. |
Collaborator
There was a problem hiding this comment.
Internally, Fiber tracks last_error and last_error_code on PaymentSession, but the public RPC response exposes the latest failure message as failed_error.
yfeng2824
reviewed
Jun 16, 2026
| 2. A nested **trampoline onion packet** (embedded in the payment onion's custom records) encodes the trampoline hops and their instructions | ||
| 3. Each trampoline node peels its layer, performs its own route-finding to the next trampoline node (or the final recipient), and forwards the payment | ||
|
|
||
| Trampoline routing is especially useful for mobile or light nodes that do not maintain a full network graph. The maximum number of trampoline hops is 5, and trampoline routing forces single-path (non-MPP) payments. |
Collaborator
There was a problem hiding this comment.
According to https://github.com/nervosnetwork/fiber/blob/v0.8.1/crates/fiber-lib/src/fiber/payment.rs#L239-L241, should we say "MPP is only allowed with a single trampoline hop; multiple trampoline hops force single-path behavior."
yfeng2824
reviewed
Jun 16, 2026
| - One or more attempts failed with retryable errors, and the retry limit has been reached. | ||
|
|
||
| **Solutions**: | ||
| - Check `last_error` on the payment to identify which attempt failed. |
Collaborator
There was a problem hiding this comment.
Again, should we use failed_error here as that's the field from RPC output.
yfeng2824
reviewed
Jun 16, 2026
|
|
||
| **Solutions**: | ||
| - Double-check that you are using the exact preimage that was used to compute the `payment_hash`. | ||
| - If generating preimages programmatically, verify the hash immediately after creation: `sha256(preimage) == payment_hash`. |
Collaborator
There was a problem hiding this comment.
Instead of hardcoding sha256(preimage) here, can we use the invoice’s hash algorithm instead since the default is ckb_hash
yfeng2824
requested changes
Jun 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.