lib.rs

// Copyright 2018-2022 Parity Technologies (UK) Ltd.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#![doc(
    html_logo_url = "https://use.ink/img/crate-docs/logo.png",
    html_favicon_url = "https://use.ink/crate-docs/favicon.png"
)]
#![cfg_attr(not(feature = "std"), no_std)]

#[cfg(not(feature = "std"))]
extern crate alloc;
extern crate core;

#[cfg(test)]
mod tests;

pub mod layout;
mod specs;
mod utils;

pub use ink_primitives::LangError;

pub use self::specs::{
    ConstructorSpec,
    ConstructorSpecBuilder,
    ContractSpec,
    ContractSpecBuilder,
    DisplayName,
    EnvironmentSpec,
    EnvironmentSpecBuilder,
    EventParamSpec,
    EventParamSpecBuilder,
    EventSpec,
    EventSpecBuilder,
    MessageParamSpec,
    MessageParamSpecBuilder,
    MessageSpec,
    MessageSpecBuilder,
    ReturnTypeSpec,
    Selector,
    TypeSpec,
};

use impl_serde::serialize as serde_hex;

#[doc(hidden)]
pub use linkme;
pub use scale_info::TypeInfo;

#[cfg(feature = "derive")]
use scale_info::{
    form::PortableForm,
    IntoPortable as _,
    PortableRegistry,
    Registry,
};
use schemars::JsonSchema;
use serde::{
    Deserialize,
    Serialize,
};

/// The metadata version of the generated ink! contract.
///
/// The serialized metadata format (which this represents) is different from the
/// version of this crate or the contract for Rust semantic versioning purposes.
///
/// # Note
///
/// Versions other than the `Default` are considered deprecated. If you want to
/// deserialize legacy metadata versions you will need to use an old version of
/// this crate.
#[derive(Debug, Serialize, Deserialize, Eq, PartialEq, JsonSchema)]
pub enum MetadataVersion {
    #[serde(rename = "4")]
    V4,
}

impl Default for MetadataVersion {
    fn default() -> Self {
        Self::V4
    }
}

/// An entire ink! project for metadata file generation purposes.
#[derive(Debug, Serialize, Deserialize, JsonSchema)]
pub struct InkProject {
    version: MetadataVersion,
    #[serde(flatten)]
    registry: PortableRegistry,
    #[serde(rename = "storage")]
    /// The layout of the storage data structure
    layout: layout::Layout<PortableForm>,
    spec: ContractSpec<PortableForm>,
}

impl InkProject {
    /// Create a new ink! project from a layout and a spec.
    pub fn new<L, S>(layout: L, spec: S) -> Self
    where
        L: Into<layout::Layout>,
        S: Into<ContractSpec>,
    {
        let mut registry = Registry::new();

        Self {
            version: Default::default(),
            layout: layout.into().into_portable(&mut registry),
            spec: spec.into().into_portable(&mut registry),
            registry: registry.into(),
        }
    }

    /// Create a new portable ink! project.
    ///
    /// The caller is responsible to register all types into the supplied registry.
    pub fn new_portable(
        layout: layout::Layout<PortableForm>,
        spec: ContractSpec<PortableForm>,
        registry: PortableRegistry,
    ) -> Self {
        Self {
            version: Default::default(),
            layout,
            spec,
            registry,
        }
    }

    /// Returns the metadata version used by the contract.
    pub fn version(&self) -> &MetadataVersion {
        &self.version
    }

    /// Returns a read-only registry of types in the contract.
    pub fn registry(&self) -> &PortableRegistry {
        &self.registry
    }

    /// Returns the storage layout of the contract.
    pub fn layout(&self) -> &layout::Layout<PortableForm> {
        &self.layout
    }

    /// Returns the specification of the contract.
    pub fn spec(&self) -> &ContractSpec<PortableForm> {
        &self.spec
    }
}

/// Collects all event definitions in the contract binary at linking time.
#[linkme::distributed_slice]
pub static EVENTS: [fn() -> EventSpec] = [..];

// todo: docs
pub trait EventMetadata {
    /// The full path to the event type, usually provided by [`core::module_path`].
    const MODULE_PATH: &'static str;

    /// Returns the metadata of the event.
    fn event_spec() -> EventSpec;
}