1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use crate::binary::Binary;
use crate::to_json_binary;
/// This is a standard IBC acknowledgement type. IBC application are free
/// to use any acknowledgement format they want. However, for compatibility
/// purposes it is recommended to use this.
///
/// The original proto definition can be found at <https://github.com/cosmos/cosmos-sdk/blob/v0.42.0/proto/ibc/core/channel/v1/channel.proto#L141-L147>
/// and <https://github.com/cosmos/ibc/tree/ed849c7bac/spec/core/ics-004-channel-and-packet-semantics#acknowledgement-envelope>.
///
/// In contrast to the original idea, [ICS-20](https://github.com/cosmos/ibc/tree/ed849c7bacf16204e9509f0f0df325391f3ce25c/spec/app/ics-020-fungible-token-transfer#technical-specification) and CosmWasm IBC protocols
/// use JSON instead of a protobuf serialization.
///
/// For compatibility, we use the field name "result" for the success case in JSON.
/// However, all Rust APIs use the term "success" for clarity and discriminability from [Result].
///
/// If ibc_receive_packet returns Err(), then x/wasm runtime will rollback the state and
/// return an error message in this format.
///
/// ## Examples
///
/// For your convenience, there are success and error constructors.
///
/// ```
/// use cosmwasm_std::StdAck;
///
/// let ack1 = StdAck::success(b"\x01"); // 0x01 is a FungibleTokenPacketSuccess from ICS-20.
/// assert!(ack1.is_success());
///
/// let ack2 = StdAck::error("kaputt"); // Some free text error message
/// assert!(ack2.is_error());
/// ```
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum StdAck {
#[serde(rename = "result")]
Success(Binary),
Error(String),
}
impl StdAck {
/// Creates a success ack with the given data
pub fn success(data: impl Into<Binary>) -> Self {
StdAck::Success(data.into())
}
/// Creates an error ack
pub fn error(err: impl Into<String>) -> Self {
StdAck::Error(err.into())
}
#[must_use = "if you intended to assert that this is a success, consider `.unwrap()` instead"]
#[inline]
pub const fn is_success(&self) -> bool {
matches!(*self, StdAck::Success(_))
}
#[must_use = "if you intended to assert that this is an error, consider `.unwrap_err()` instead"]
#[inline]
pub const fn is_error(&self) -> bool {
!self.is_success()
}
/// Serialized the ack to binary using JSON. This used for setting the acknowledgement
/// field in IbcReceiveResponse.
///
/// ## Examples
///
/// Show how the acknowledgement looks on the write:
///
/// ```
/// # use cosmwasm_std::StdAck;
/// let ack1 = StdAck::success(b"\x01"); // 0x01 is a FungibleTokenPacketSuccess from ICS-20.
/// assert_eq!(ack1.to_binary(), br#"{"result":"AQ=="}"#);
///
/// let ack2 = StdAck::error("kaputt"); // Some free text error message
/// assert_eq!(ack2.to_binary(), br#"{"error":"kaputt"}"#);
/// ```
///
/// Set acknowledgement field in `IbcReceiveResponse`:
///
/// ```
/// use cosmwasm_std::{StdAck, IbcReceiveResponse};
///
/// let ack = StdAck::success(b"\x01"); // 0x01 is a FungibleTokenPacketSuccess from ICS-20.
///
/// let res: IbcReceiveResponse = IbcReceiveResponse::new().set_ack(ack.to_binary());
/// let res: IbcReceiveResponse = IbcReceiveResponse::new().set_ack(ack); // Does the same but consumes the instance
/// ```
pub fn to_binary(&self) -> Binary {
// We need a non-failing StdAck -> Binary conversion to allow using StdAck in
// `impl Into<Binary>` arguments.
// Pretty sure this cannot fail. If that changes we can create a non-failing implementation here.
to_json_binary(&self).unwrap()
}
pub fn unwrap(self) -> Binary {
match self {
StdAck::Success(data) => data,
StdAck::Error(err) => panic!("{}", err),
}
}
pub fn unwrap_err(self) -> String {
match self {
StdAck::Success(_) => panic!("not an error"),
StdAck::Error(err) => err,
}
}
}
impl From<StdAck> for Binary {
fn from(original: StdAck) -> Binary {
original.to_binary()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn stdack_success_works() {
let success = StdAck::success(b"foo");
match success {
StdAck::Success(data) => assert_eq!(data, b"foo"),
StdAck::Error(_err) => panic!("must not be an error"),
}
}
#[test]
fn stdack_error_works() {
let err = StdAck::error("bar");
match err {
StdAck::Success(_data) => panic!("must not be a success"),
StdAck::Error(err) => assert_eq!(err, "bar"),
}
}
#[test]
fn stdack_is_success_is_error_work() {
let success = StdAck::success(b"foo");
let err = StdAck::error("bar");
// is_success
assert!(success.is_success());
assert!(!err.is_success());
// is_eror
assert!(!success.is_error());
assert!(err.is_error());
}
#[test]
fn stdack_to_binary_works() {
let ack1 = StdAck::success(b"\x01");
assert_eq!(ack1.to_binary(), br#"{"result":"AQ=="}"#);
let ack2 = StdAck::error("kaputt");
assert_eq!(ack2.to_binary(), br#"{"error":"kaputt"}"#);
}
}