|
| 1 | +package consensus |
| 2 | + |
| 3 | +import ( |
| 4 | + "context" |
| 5 | + "errors" |
| 6 | + |
| 7 | + "go.opencensus.io/stats" |
| 8 | + |
| 9 | + "github.com/filecoin-project/go-address" |
| 10 | + "github.com/filecoin-project/go-state-types/abi" |
| 11 | + "github.com/filecoin-project/go-state-types/big" |
| 12 | + "github.com/filecoin-project/go-state-types/network" |
| 13 | + cid "github.com/ipfs/go-cid" |
| 14 | + logging "github.com/ipfs/go-log/v2" |
| 15 | + |
| 16 | + "github.com/filecoin-project/lotus/chain/types" |
| 17 | + "github.com/filecoin-project/lotus/chain/vm" |
| 18 | + "github.com/filecoin-project/lotus/metrics" |
| 19 | +) |
| 20 | + |
| 21 | +var rlog = logging.Logger("reservations") |
| 22 | + |
| 23 | +// ReservationsEnabled returns true when tipset reservations should be attempted. |
| 24 | +// Before the reservations activation network version, this helper consults the |
| 25 | +// MultiStageReservations feature flag. At or after the activation network |
| 26 | +// version, reservations are always enabled and become consensus-critical. |
| 27 | +func ReservationsEnabled(nv network.Version) bool { |
| 28 | + // After activation, reservations are required regardless of feature flags. |
| 29 | + if nv >= vm.ReservationsActivationNetworkVersion() { |
| 30 | + return true |
| 31 | + } |
| 32 | + |
| 33 | + // Pre-activation: best-effort mode controlled by the feature flag. |
| 34 | + return Feature.MultiStageReservations |
| 35 | +} |
| 36 | + |
| 37 | +// buildReservationPlan aggregates per-sender gas reservations across the full |
| 38 | +// tipset. The amount reserved for each message is gas_limit * gas_fee_cap, and |
| 39 | +// messages are deduplicated by CID across all blocks in canonical order, |
| 40 | +// matching processedMsgs handling in ApplyBlocks. |
| 41 | +func buildReservationPlan(bms []FilecoinBlockMessages) map[address.Address]abi.TokenAmount { |
| 42 | + plan := make(map[address.Address]abi.TokenAmount) |
| 43 | + seen := make(map[cid.Cid]struct{}) |
| 44 | + |
| 45 | + for _, b := range bms { |
| 46 | + // canonical order is preserved in the combined slices append below |
| 47 | + for _, cm := range append(b.BlsMessages, b.SecpkMessages...) { |
| 48 | + m := cm.VMMessage() |
| 49 | + mcid := m.Cid() |
| 50 | + if _, ok := seen[mcid]; ok { |
| 51 | + continue |
| 52 | + } |
| 53 | + seen[mcid] = struct{}{} |
| 54 | + // Only explicit messages are included in blocks; implicit messages are applied separately. |
| 55 | + cost := types.BigMul(types.NewInt(uint64(m.GasLimit)), m.GasFeeCap) |
| 56 | + if prev, ok := plan[m.From]; ok { |
| 57 | + plan[m.From] = types.BigAdd(prev, cost) |
| 58 | + } else { |
| 59 | + plan[m.From] = cost |
| 60 | + } |
| 61 | + } |
| 62 | + } |
| 63 | + return plan |
| 64 | +} |
| 65 | + |
| 66 | +// startReservations is a helper that starts a reservation session on the VM if enabled. |
| 67 | +// If the computed plan is empty (no explicit messages), Begin is skipped entirely. |
| 68 | +func startReservations(ctx context.Context, vmi vm.Interface, bms []FilecoinBlockMessages, nv network.Version) error { |
| 69 | + if !ReservationsEnabled(nv) { |
| 70 | + return nil |
| 71 | + } |
| 72 | + |
| 73 | + plan := buildReservationPlan(bms) |
| 74 | + if len(plan) == 0 { |
| 75 | + rlog.Debugw("skipping tipset reservations for empty plan") |
| 76 | + return nil |
| 77 | + } |
| 78 | + |
| 79 | + total := abi.NewTokenAmount(0) |
| 80 | + for _, amt := range plan { |
| 81 | + total = big.Add(total, amt) |
| 82 | + } |
| 83 | + |
| 84 | + stats.Record(ctx, |
| 85 | + metrics.ReservationPlanSenders.M(int64(len(plan))), |
| 86 | + metrics.ReservationPlanTotal.M(total.Int64()), |
| 87 | + ) |
| 88 | + |
| 89 | + rlog.Infow("starting tipset reservations", "senders", len(plan), "total", total) |
| 90 | + if err := vmi.StartTipsetReservations(ctx, plan); err != nil { |
| 91 | + return handleReservationError("begin", err, nv) |
| 92 | + } |
| 93 | + return nil |
| 94 | +} |
| 95 | + |
| 96 | +// endReservations ends the active reservation session if enabled. |
| 97 | +func endReservations(ctx context.Context, vmi vm.Interface, nv network.Version) error { |
| 98 | + if !ReservationsEnabled(nv) { |
| 99 | + return nil |
| 100 | + } |
| 101 | + if err := vmi.EndTipsetReservations(ctx); err != nil { |
| 102 | + return handleReservationError("end", err, nv) |
| 103 | + } |
| 104 | + return nil |
| 105 | +} |
| 106 | + |
| 107 | +// handleReservationError interprets Begin/End reservation errors according to |
| 108 | +// network version and feature flags, deciding whether to fall back to legacy |
| 109 | +// mode (pre-activation, non-strict) or surface the error. |
| 110 | +func handleReservationError(stage string, err error, nv network.Version) error { |
| 111 | + if err == nil { |
| 112 | + return nil |
| 113 | + } |
| 114 | + |
| 115 | + // Post-activation: reservations are consensus-critical; all Begin/End |
| 116 | + // errors surface to the caller. ErrReservationsNotImplemented becomes a |
| 117 | + // node error (engine too old) under active rules. |
| 118 | + if nv >= vm.ReservationsActivationNetworkVersion() { |
| 119 | + return err |
| 120 | + } |
| 121 | + |
| 122 | + // Pre-activation: ErrNotImplemented is always treated as a benign signal |
| 123 | + // that the engine does not support reservations yet; fall back to legacy |
| 124 | + // mode regardless of strictness. |
| 125 | + if errors.Is(err, vm.ErrReservationsNotImplemented) { |
| 126 | + rlog.Debugw("tipset reservations not implemented; continuing in legacy mode", |
| 127 | + "stage", stage, "error", err) |
| 128 | + return nil |
| 129 | + } |
| 130 | + |
| 131 | + // Node-error classes: always surface as errors, even pre-activation. |
| 132 | + if errors.Is(err, vm.ErrReservationsSessionOpen) || |
| 133 | + errors.Is(err, vm.ErrReservationsSessionClosed) || |
| 134 | + errors.Is(err, vm.ErrReservationsNonZeroRemainder) || |
| 135 | + errors.Is(err, vm.ErrReservationsOverflow) || |
| 136 | + errors.Is(err, vm.ErrReservationsInvariantViolation) { |
| 137 | + return err |
| 138 | + } |
| 139 | + |
| 140 | + // Reservation failures toggled by strict mode. When strict is disabled, |
| 141 | + // treat these as best-effort pre-activation and fall back to legacy mode. |
| 142 | + switch { |
| 143 | + case errors.Is(err, vm.ErrReservationsInsufficientFunds), errors.Is(err, vm.ErrReservationsPlanTooLarge): |
| 144 | + if Feature.MultiStageReservationsStrict { |
| 145 | + return err |
| 146 | + } |
| 147 | + rlog.Debugw("tipset reservations failed pre-activation; continuing in legacy mode (non-strict)", |
| 148 | + "stage", stage, "error", err) |
| 149 | + return nil |
| 150 | + default: |
| 151 | + // Unknown errors pre-activation are treated as node errors. |
| 152 | + return err |
| 153 | + } |
| 154 | +} |
0 commit comments