linera_base/
abi.rs

1// Copyright (c) Zefchain Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4//! This module defines the notion of Application Binary Interface (ABI) for Linera
5//! applications across Wasm and native architectures.
6
7use std::fmt::Debug;
8
9use serde::{de::DeserializeOwned, Serialize};
10
11// ANCHOR: abi
12/// A trait that includes all the types exported by a Linera application (both contract
13/// and service).
14pub trait Abi: ContractAbi + ServiceAbi {}
15// ANCHOR_END: abi
16
17// T::Parameters is duplicated for simplicity but it must match.
18impl<T> Abi for T where T: ContractAbi + ServiceAbi {}
19
20// ANCHOR: contract_abi
21/// A trait that includes all the types exported by a Linera application contract.
22pub trait ContractAbi {
23    /// The type of operation executed by the application.
24    ///
25    /// Operations are transactions directly added to a block by the creator (and signer)
26    /// of the block. Users typically use operations to start interacting with an
27    /// application on their own chain.
28    type Operation: Serialize + DeserializeOwned + Send + Sync + Debug + 'static;
29
30    /// The response type of an application call.
31    type Response: Serialize + DeserializeOwned + Send + Sync + Debug + 'static;
32
33    /// How the `Operation` is deserialized
34    fn deserialize_operation(operation: Vec<u8>) -> Result<Self::Operation, String> {
35        bcs::from_bytes(&operation)
36            .map_err(|e| format!("BCS deserialization error {e:?} for operation {operation:?}"))
37    }
38
39    /// How the `Operation` is serialized
40    fn serialize_operation(operation: &Self::Operation) -> Result<Vec<u8>, String> {
41        bcs::to_bytes(operation)
42            .map_err(|e| format!("BCS serialization error {e:?} for operation {operation:?}"))
43    }
44
45    /// How the `Response` is deserialized
46    fn deserialize_response(response: Vec<u8>) -> Result<Self::Response, String> {
47        bcs::from_bytes(&response)
48            .map_err(|e| format!("BCS deserialization error {e:?} for response {response:?}"))
49    }
50
51    /// How the `Response` is serialized
52    fn serialize_response(response: Self::Response) -> Result<Vec<u8>, String> {
53        bcs::to_bytes(&response)
54            .map_err(|e| format!("BCS serialization error {e:?} for response {response:?}"))
55    }
56}
57// ANCHOR_END: contract_abi
58
59// ANCHOR: service_abi
60/// A trait that includes all the types exported by a Linera application service.
61pub trait ServiceAbi {
62    /// The type of a query receivable by the application's service.
63    type Query: Serialize + DeserializeOwned + Send + Sync + Debug + 'static;
64
65    /// The response type of the application's service.
66    type QueryResponse: Serialize + DeserializeOwned + Send + Sync + Debug + 'static;
67}
68// ANCHOR_END: service_abi
69
70/// Marker trait to help importing contract types.
71pub trait WithContractAbi {
72    /// The contract types to import.
73    type Abi: ContractAbi;
74}
75
76impl<A> ContractAbi for A
77where
78    A: WithContractAbi,
79{
80    type Operation = <<A as WithContractAbi>::Abi as ContractAbi>::Operation;
81    type Response = <<A as WithContractAbi>::Abi as ContractAbi>::Response;
82}
83
84/// Marker trait to help importing service types.
85pub trait WithServiceAbi {
86    /// The service types to import.
87    type Abi: ServiceAbi;
88}
89
90impl<A> ServiceAbi for A
91where
92    A: WithServiceAbi,
93{
94    type Query = <<A as WithServiceAbi>::Abi as ServiceAbi>::Query;
95    type QueryResponse = <<A as WithServiceAbi>::Abi as ServiceAbi>::QueryResponse;
96}
linera_base/abi.rs

linera_base/
abi.rs
