Skip to content

Commit

Permalink
Add StdAck
Browse files Browse the repository at this point in the history
  • Loading branch information
webmaster128 committed Aug 15, 2023
1 parent d5eaa62 commit 9cc2c89
Show file tree
Hide file tree
Showing 3 changed files with 160 additions and 0 deletions.
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,9 @@ and this project adheres to
### Added

- cosmwasm-std: Implement `Not` for `Uint{64,128,256}` ([#1799]).
- cosmwasm-std: Add `StdAck`. ([#1512])

[#1512]: https://github.com/CosmWasm/cosmwasm/issues/1512
[#1799]: https://github.com/CosmWasm/cosmwasm/pull/1799

### Changed
Expand Down
2 changes: 2 additions & 0 deletions packages/std/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ mod query;
mod results;
mod sections;
mod serde;
mod stdack;
mod storage;
mod timestamp;
mod traits;
Expand Down Expand Up @@ -86,6 +87,7 @@ pub use crate::results::{DistributionMsg, StakingMsg};
#[cfg(feature = "stargate")]
pub use crate::results::{GovMsg, VoteOption};
pub use crate::serde::{from_binary, from_slice, to_binary, to_vec};
pub use crate::stdack::StdAck;
pub use crate::storage::MemoryStorage;
pub use crate::timestamp::Timestamp;
pub use crate::traits::{Api, Querier, QuerierResult, QuerierWrapper, Storage};
Expand Down
156 changes: 156 additions & 0 deletions packages/std/src/stdack.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,156 @@
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use crate::binary::Binary;
use crate::to_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.
///
/// 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 {
Result(Binary),
Error(String),
}

impl StdAck {
/// Creates a success ack with the given data
pub fn success(data: impl Into<Binary>) -> Self {
StdAck::Result(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::Result(_))
}

#[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`:
///
/// ```ignore
/// use cosmwasm_std::{StdAck, IbcReceiveResponse};
///
/// let ack = StdAck::success(b"\x01"); // 0x01 is a FungibleTokenPacketSuccess from ICS-20.
///
/// let res = IbcReceiveResponse::new().set_ack(ack.to_binary());
/// let res = IbcReceiveResponse::new().set_ack(ack); // Does the same but consumes the instance
/// ```
pub fn to_binary(&self) -> Binary {
// Pretty sure this cannot fail. If that changes we can create a non-failing implementation here.
to_binary(&self).unwrap()
}

pub fn unwrap(self) -> Binary {
match self {
StdAck::Result(data) => data,
StdAck::Error(err) => panic!("{}", err),
}
}

pub fn unwrap_err(self) -> String {
match self {
StdAck::Result(_) => 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::Result(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::Result(_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"}"#);
}
}

0 comments on commit 9cc2c89

Please sign in to comment.