Merge pull request #5840 from filecoin-project/docs/replay-replace-note

api: Document StateReplay replaced message behavior

api/api_full.go

@@ -67,6 +67,17 @@ type FullNode interface {
 	ChainGetTipSet(context.Context, types.TipSetKey) (*types.TipSet, error)
 
 	// ChainGetBlockMessages returns messages stored in the specified block.
+	//
+	// Note: If there are multiple blocks in a tipset, it's likely that some
+	// messages will be duplicated. It's also possible for blocks in a tipset to have
+	// different messages from the same sender at the same nonce. When that happens,
+	// only the first message (in a block with lowest ticket) will be considered
+	// for execution
+	//
+	// NOTE: THIS METHOD SHOULD ONLY BE USED FOR GETTING MESSAGES IN A SPECIFIC BLOCK
+	//
+	// DO NOT USE THIS METHOD TO GET MESSAGES INCLUDED IN A TIPSET
+	// Use ChainGetParentMessages, which will perform correct message deduplication
 	ChainGetBlockMessages(ctx context.Context, blockCid cid.Cid) (*BlockMessages, error)
 
 	// ChainGetParentReceipts returns receipts for messages in parent tipset of
@@ -350,7 +361,22 @@ type FullNode interface {
 	// tipset.
 	StateCall(context.Context, *types.Message, types.TipSetKey) (*InvocResult, error)
 	// StateReplay replays a given message, assuming it was included in a block in the specified tipset.
-	// If no tipset key is provided, the appropriate tipset is looked up.
+	//
+	// If a tipset key is provided, and a replacing message is found on chain,
+	// the method will return an error saying that the message wasn't found
+	//
+	// If no tipset key is provided, the appropriate tipset is looked up, and if
+	// the message was gas-repriced, the on-chain message will be replayed - in
+	// that case the returned InvocResult.MsgCid will not match the Cid param
+	//
+	// If the caller wants to ensure that exactly the requested message was executed,
+	// they MUST check that InvocResult.MsgCid is equal to the provided Cid.
+	// Without this check both the requested and original message may appear as
+	// successfully executed on-chain, which may look like a double-spend.
+	//
+	// A replacing message is a message with a different CID, any of Gas values, and
+	// different signature, but with all other parameters matching (source/destination,
+	// nonce, params, etc.)
 	StateReplay(context.Context, types.TipSetKey, cid.Cid) (*InvocResult, error)
 	// StateGetActor returns the indicated actor's nonce and balance.
 	StateGetActor(ctx context.Context, actor address.Address, tsk types.TipSetKey) (*types.Actor, error)
@@ -494,7 +520,7 @@ type FullNode interface {
 	// NOTE: If the requested message was replaced, this method will return the receipt
 	// for the replacing message - if the caller needs the receipt for exactly the
 	// requested message, use StateSearchMsg().Receipt, and check that MsgLookup.Message
-	// is matching the requseted CID
+	// is matching the requested CID
 	//
 	// DEPRECATED: Use StateSearchMsg, this method won't be supported in v1 API
 	StateGetReceipt(context.Context, cid.Cid, types.TipSetKey) (*types.MessageReceipt, error)
@@ -502,7 +528,37 @@ type FullNode interface {
 	StateMinerSectorCount(context.Context, address.Address, types.TipSetKey) (MinerSectors, error)
 	// StateCompute is a flexible command that applies the given messages on the given tipset.
 	// The messages are run as though the VM were at the provided height.
-	StateCompute(context.Context, abi.ChainEpoch, []*types.Message, types.TipSetKey) (*ComputeStateOutput, error)
+	//
+	// When called, StateCompute will:
+	// - Load the provided tipset, or use the current chain head if not provided
+	// - Compute the tipset state of the provided tipset on top of the parent state
+	//   - (note that this step runs before vmheight is applied to the execution)
+	//   - Execute state upgrade if any were scheduled at the epoch, or in null
+	//     blocks preceding the tipset
+	//   - Call the cron actor on null blocks preceding the tipset
+	//   - For each block in the tipset
+	//     - Apply messages in blocks in the specified
+	//     - Award block reward by calling the reward actor
+	//   - Call the cron actor for the current epoch
+	// - If the specified vmheight is higher than the current epoch, apply any
+	//   needed state upgrades to the state
+	// - Apply the specified messages to the state
+	//
+	// The vmheight parameter sets VM execution epoch, and can be used to simulate
+	// message execution in different network versions. If the specified vmheight
+	// epoch is higher than the epoch of the specified tipset, any state upgrades
+	// until the vmheight will be executed on the state before applying messages
+	// specified by the user.
+	//
+	// Note that the initial tipset state computation is not affected by the
+	// vmheight parameter - only the messages in the `apply` set are
+	//
+	// If the caller wants to simply compute the state, vmheight should be set to
+	// the epoch of the specified tipset.
+	//
+	// Messages in the `apply` parameter must have the correct nonces, and gas
+	// values set.
+	StateCompute(ctx context.Context, vmheight abi.ChainEpoch, apply []*types.Message, tsk types.TipSetKey) (*ComputeStateOutput, error)
 	// StateVerifierStatus returns the data cap for the given address.
 	// Returns nil if there is no entry in the data cap table for the
 	// address.

documentation/en/api-methods.md

@@ -445,6 +445,17 @@ Response:
 ### ChainGetBlockMessages
 ChainGetBlockMessages returns messages stored in the specified block.
 
+Note: If there are multiple blocks in a tipset, it's likely that some
+messages will be duplicated. It's also possible for blocks in a tipset to have
+different messages from the same sender at the same nonce. When that happens,
+only the first message (in a block with lowest ticket) will be considered
+for execution
+
+NOTE: THIS METHOD SHOULD ONLY BE USED FOR GETTING MESSAGES IN A SPECIFIC BLOCK
+
+DO NOT USE THIS METHOD TO GET MESSAGES INCLUDED IN A TIPSET
+Use ChainGetParentMessages, which will perform correct message deduplication
+
 
 Perms: read
 
@@ -3586,6 +3597,36 @@ Response: `"0"`
 StateCompute is a flexible command that applies the given messages on the given tipset.
 The messages are run as though the VM were at the provided height.
 
+When called, StateCompute will:
+- Load the provided tipset, or use the current chain head if not provided
+- Compute the tipset state of the provided tipset on top of the parent state
+  - (note that this step runs before vmheight is applied to the execution)
+  - Execute state upgrade if any were scheduled at the epoch, or in null
+    blocks preceding the tipset
+  - Call the cron actor on null blocks preceding the tipset
+  - For each block in the tipset
+    - Apply messages in blocks in the specified
+    - Award block reward by calling the reward actor
+  - Call the cron actor for the current epoch
+- If the specified vmheight is higher than the current epoch, apply any
+  needed state upgrades to the state
+- Apply the specified messages to the state
+
+The vmheight parameter sets VM execution epoch, and can be used to simulate
+message execution in different network versions. If the specified vmheight
+epoch is higher than the epoch of the specified tipset, any state upgrades
+until the vmheight will be executed on the state before applying messages
+specified by the user.
+
+Note that the initial tipset state computation is not affected by the
+vmheight parameter - only the messages in the `apply` set are
+
+If the caller wants to simply compute the state, vmheight should be set to
+the epoch of the specified tipset.
+
+Messages in the `apply` parameter must have the correct nonces, and gas
+values set.
+
 
 Perms: read
 
@@ -3713,7 +3754,7 @@ matching gas-repriced replacing message
 NOTE: If the requested message was replaced, this method will return the receipt
 for the replacing message - if the caller needs the receipt for exactly the
 requested message, use StateSearchMsg().Receipt, and check that MsgLookup.Message
-is matching the requseted CID
+is matching the requested CID
 
 DEPRECATED: Use StateSearchMsg, this method won't be supported in v1 API
 
@@ -4479,7 +4520,22 @@ Response:
 
 ### StateReplay
 StateReplay replays a given message, assuming it was included in a block in the specified tipset.
-If no tipset key is provided, the appropriate tipset is looked up.
+
+If a tipset key is provided, and a replacing message is found on chain,
+the method will return an error saying that the message wasn't found
+
+If no tipset key is provided, the appropriate tipset is looked up, and if
+the message was gas-repriced, the on-chain message will be replayed - in
+that case the returned InvocResult.MsgCid will not match the Cid param
+
+If the caller wants to ensure that exactly the requested message was executed,
+they MUST check that InvocResult.MsgCid is equal to the provided Cid.
+Without this check both the requested and original message may appear as
+successfully executed on-chain, which may look like a double-spend.
+
+A replacing message is a message with a different CID, any of Gas values, and
+different signature, but with all other parameters matching (source/destination,
+nonce, params, etc.)
 
 
 Perms: read