diff --git a/api/api_full.go b/api/api_full.go index ca3a02c747e..cbd23564616 100644 --- a/api/api_full.go +++ b/api/api_full.go @@ -70,7 +70,8 @@ type FullNode interface { ChainGetBlockMessages(ctx context.Context, blockCid cid.Cid) (*BlockMessages, error) // ChainGetParentReceipts returns receipts for messages in parent tipset of - // the specified block. + // the specified block. The receipts in the list returned is one-to-one with the + // messages returned by a call to ChainGetParentMessages with the same blockCid. ChainGetParentReceipts(ctx context.Context, blockCid cid.Cid) ([]*types.MessageReceipt, error) // ChainGetParentMessages returns messages stored in parent tipset of the @@ -402,15 +403,71 @@ type FullNode interface { // StateSectorPartition finds deadline/partition with the specified sector StateSectorPartition(ctx context.Context, maddr address.Address, sectorNumber abi.SectorNumber, tok types.TipSetKey) (*miner.SectorLocation, error) // StateSearchMsg searches for a message in the chain, and returns its receipt and the tipset where it was executed + // + // NOTE: If a replacing message is found on chain, this method will return + // a MsgLookup for the replacing message - the MsgLookup.Message will be a different + // CID than the one provided in the 'cid' param, MsgLookup.Receipt will contain the + // result of the execution of the replacing message. + // + // If the caller wants to ensure that exactly the requested message was executed, + // they MUST check that MsgLookup.Message 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.) StateSearchMsg(context.Context, cid.Cid) (*MsgLookup, error) // StateSearchMsgLimited looks back up to limit epochs in the chain for a message, and returns its receipt and the tipset where it was executed + // + // NOTE: If a replacing message is found on chain, this method will return + // a MsgLookup for the replacing message - the MsgLookup.Message will be a different + // CID than the one provided in the 'cid' param, MsgLookup.Receipt will contain the + // result of the execution of the replacing message. + // + // If the caller wants to ensure that exactly the requested message was executed, + // they MUST check that MsgLookup.Message 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.) StateSearchMsgLimited(ctx context.Context, msg cid.Cid, limit abi.ChainEpoch) (*MsgLookup, error) // StateWaitMsg looks back in the chain for a message. If not found, it blocks until the // message arrives on chain, and gets to the indicated confidence depth. + // + // NOTE: If a replacing message is found on chain, this method will return + // a MsgLookup for the replacing message - the MsgLookup.Message will be a different + // CID than the one provided in the 'cid' param, MsgLookup.Receipt will contain the + // result of the execution of the replacing message. + // + // If the caller wants to ensure that exactly the requested message was executed, + // they MUST check that MsgLookup.Message 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.) StateWaitMsg(ctx context.Context, cid cid.Cid, confidence uint64) (*MsgLookup, error) // StateWaitMsgLimited looks back up to limit epochs in the chain for a message. // If not found, it blocks until the message arrives on chain, and gets to the // indicated confidence depth. + // + // NOTE: If a replacing message is found on chain, this method will return + // a MsgLookup for the replacing message - the MsgLookup.Message will be a different + // CID than the one provided in the 'cid' param, MsgLookup.Receipt will contain the + // result of the execution of the replacing message. + // + // If the caller wants to ensure that exactly the requested message was executed, + // they MUST check that MsgLookup.Message 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.) StateWaitMsgLimited(ctx context.Context, cid cid.Cid, confidence uint64, limit abi.ChainEpoch) (*MsgLookup, error) // StateListMiners returns the addresses of every miner that has claimed power in the Power Actor StateListMiners(context.Context, types.TipSetKey) ([]address.Address, error) @@ -431,7 +488,15 @@ type FullNode interface { // StateChangedActors returns all the actors whose states change between the two given state CIDs // TODO: Should this take tipset keys instead? StateChangedActors(context.Context, cid.Cid, cid.Cid) (map[string]types.Actor, error) - // StateGetReceipt returns the message receipt for the given message + // StateGetReceipt returns the message receipt for the given message or for a + // 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 + // + // DEPRECATED: Use StateSearchMsg, this method won't be supported in v1 API StateGetReceipt(context.Context, cid.Cid, types.TipSetKey) (*types.MessageReceipt, error) // StateMinerSectorCount returns the number of sectors in a miner's sector set and proving set StateMinerSectorCount(context.Context, address.Address, types.TipSetKey) (MinerSectors, error) diff --git a/documentation/en/api-methods.md b/documentation/en/api-methods.md index 49afeeb1a0a..34b94ff4403 100644 --- a/documentation/en/api-methods.md +++ b/documentation/en/api-methods.md @@ -540,7 +540,8 @@ Response: `null` ### ChainGetParentReceipts ChainGetParentReceipts returns receipts for messages in parent tipset of -the specified block. +the specified block. The receipts in the list returned is one-to-one with the +messages returned by a call to ChainGetParentMessages with the same blockCid. Perms: read @@ -3686,7 +3687,15 @@ Response: ``` ### StateGetReceipt -StateGetReceipt returns the message receipt for the given message +StateGetReceipt returns the message receipt for the given message or for a +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 + +DEPRECATED: Use StateSearchMsg, this method won't be supported in v1 API Perms: read @@ -4544,6 +4553,20 @@ Response: ### StateSearchMsg StateSearchMsg searches for a message in the chain, and returns its receipt and the tipset where it was executed +NOTE: If a replacing message is found on chain, this method will return +a MsgLookup for the replacing message - the MsgLookup.Message will be a different +CID than the one provided in the 'cid' param, MsgLookup.Receipt will contain the +result of the execution of the replacing message. + +If the caller wants to ensure that exactly the requested message was executed, +they MUST check that MsgLookup.Message 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 @@ -4583,6 +4606,20 @@ Response: ### StateSearchMsgLimited StateSearchMsgLimited looks back up to limit epochs in the chain for a message, and returns its receipt and the tipset where it was executed +NOTE: If a replacing message is found on chain, this method will return +a MsgLookup for the replacing message - the MsgLookup.Message will be a different +CID than the one provided in the 'cid' param, MsgLookup.Receipt will contain the +result of the execution of the replacing message. + +If the caller wants to ensure that exactly the requested message was executed, +they MUST check that MsgLookup.Message 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 @@ -4877,6 +4914,20 @@ Response: `"0"` StateWaitMsg looks back in the chain for a message. If not found, it blocks until the message arrives on chain, and gets to the indicated confidence depth. +NOTE: If a replacing message is found on chain, this method will return +a MsgLookup for the replacing message - the MsgLookup.Message will be a different +CID than the one provided in the 'cid' param, MsgLookup.Receipt will contain the +result of the execution of the replacing message. + +If the caller wants to ensure that exactly the requested message was executed, +they MUST check that MsgLookup.Message 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 @@ -4919,6 +4970,20 @@ StateWaitMsgLimited looks back up to limit epochs in the chain for a message. If not found, it blocks until the message arrives on chain, and gets to the indicated confidence depth. +NOTE: If a replacing message is found on chain, this method will return +a MsgLookup for the replacing message - the MsgLookup.Message will be a different +CID than the one provided in the 'cid' param, MsgLookup.Receipt will contain the +result of the execution of the replacing message. + +If the caller wants to ensure that exactly the requested message was executed, +they MUST check that MsgLookup.Message 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