ink_metadata/
lib.rs

1// Copyright (C) Use Ink (UK) Ltd.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15#![doc(
16    html_logo_url = "https://use.ink/img/crate-docs/logo.png",
17    html_favicon_url = "https://use.ink/crate-docs/favicon.png"
18)]
19#![cfg_attr(not(feature = "std"), no_std)]
20
21#[cfg(not(feature = "std"))]
22extern crate alloc;
23extern crate core;
24
25#[cfg(test)]
26mod tests;
27
28pub mod layout;
29mod specs;
30mod utils;
31
32pub use ink_primitives::LangError;
33
34pub use self::specs::{
35    ConstructorSpec,
36    ConstructorSpecBuilder,
37    ContractSpec,
38    ContractSpecBuilder,
39    DisplayName,
40    EnvironmentSpec,
41    EnvironmentSpecBuilder,
42    EventParamSpec,
43    EventParamSpecBuilder,
44    EventSpec,
45    EventSpecBuilder,
46    MessageParamSpec,
47    MessageParamSpecBuilder,
48    MessageSpec,
49    MessageSpecBuilder,
50    ReturnTypeSpec,
51    Selector,
52    TypeSpec,
53};
54
55use impl_serde::serialize as serde_hex;
56
57#[doc(hidden)]
58pub use linkme;
59pub use scale_info::TypeInfo;
60
61#[cfg(feature = "derive")]
62use scale_info::{
63    form::PortableForm,
64    IntoPortable as _,
65    PortableRegistry,
66    Registry,
67};
68use schemars::JsonSchema;
69use serde::{
70    Deserialize,
71    Serialize,
72};
73
74/// The metadata version of the generated ink! contract.
75///
76/// The serialized metadata format (which this represents) is different from the
77/// version of this crate or the contract for Rust semantic versioning purposes.
78const METADATA_VERSION: u64 = 5;
79
80/// An entire ink! project for metadata file generation purposes.
81#[derive(Debug, Serialize, Deserialize, JsonSchema)]
82pub struct InkProject {
83    version: u64,
84    #[serde(flatten)]
85    registry: PortableRegistry,
86    #[serde(rename = "storage")]
87    /// The layout of the storage data structure
88    layout: layout::Layout<PortableForm>,
89    spec: ContractSpec<PortableForm>,
90}
91
92impl InkProject {
93    /// Create a new ink! project from a layout and a spec.
94    pub fn new<L, S>(layout: L, spec: S) -> Self
95    where
96        L: Into<layout::Layout>,
97        S: Into<ContractSpec>,
98    {
99        let mut registry = Registry::new();
100
101        Self {
102            version: METADATA_VERSION,
103            layout: layout.into().into_portable(&mut registry),
104            spec: spec.into().into_portable(&mut registry),
105            registry: registry.into(),
106        }
107    }
108
109    /// Create a new portable ink! project.
110    ///
111    /// The caller is responsible to register all types into the supplied registry.
112    pub fn new_portable(
113        layout: layout::Layout<PortableForm>,
114        spec: ContractSpec<PortableForm>,
115        registry: PortableRegistry,
116    ) -> Self {
117        Self {
118            version: METADATA_VERSION,
119            layout,
120            spec,
121            registry,
122        }
123    }
124
125    /// Returns the metadata version used by the contract.
126    pub fn version(&self) -> u64 {
127        self.version
128    }
129
130    /// Returns a read-only registry of types in the contract.
131    pub fn registry(&self) -> &PortableRegistry {
132        &self.registry
133    }
134
135    /// Returns the storage layout of the contract.
136    pub fn layout(&self) -> &layout::Layout<PortableForm> {
137        &self.layout
138    }
139
140    /// Returns the specification of the contract.
141    pub fn spec(&self) -> &ContractSpec<PortableForm> {
142        &self.spec
143    }
144}
145
146/// Any event which derives `#[derive(ink::EventMetadata)]` and is used in the contract
147/// binary will have its implementation added to this distributed slice at linking time.
148#[linkme::distributed_slice]
149pub static EVENTS: [fn() -> EventSpec] = [..];
150
151/// Collect the [`EventSpec`] metadata of all event definitions linked and used in the
152/// binary.
153pub fn collect_events() -> Vec<EventSpec> {
154    EVENTS.iter().map(|event| event()).collect()
155}
156
157/// Provides metadata about an ink! event.
158///
159/// Implementations must be registered into the [`static@EVENTS`] distributed slice, in
160/// order to be included in the contract metadata. This is done automatically by the
161/// `#[derive(ink::EventMetadata)]`
162pub trait EventMetadata {
163    /// The full path to the event type, usually provided by [`module_path`].
164    const MODULE_PATH: &'static str;
165
166    /// Returns the metadata of the event.
167    fn event_spec() -> EventSpec;
168}