Unverified Commit 4770498c authored by Hero Bird's avatar Hero Bird Committed by GitHub
Browse files

Minor API surface clean-up (#502)

* [env] remove crate-level re-exports for the hash module

* [env] rename ink_env::println -> debug_println

This makes the usage intent clearer.

* [lang] remove deprecated method

* [lang] hide all definitions that are only needed for codegen purposes

* [lang] remove False, move True

* [lang] remove unnecessary where bounds

* [lang] add EnvAccess forwarding for built-in crypto hashes

* [README] add ink_lang doc link

* [env] fix on-chain compilation

* [lang] apply clippy suggestion
parent cfe52e98
Pipeline #109328 passed with stages
in 4 minutes and 35 seconds
......@@ -20,6 +20,8 @@
[h2]: https://paritytech.github.io/ink/ink_metadata
[i1]: https://img.shields.io/badge/docs-prelude-blue.svg
[i2]: https://paritytech.github.io/ink/ink_prelude
[j1]: https://img.shields.io/badge/docs-lang-blue.svg
[j2]: https://paritytech.github.io/ink/ink_lang
**IMPORTANT NOTE:** WORK IN PROGRESS! Do not expect this to be working.
......@@ -29,9 +31,9 @@ For more information please visit [the ink! tutorial](https://substrate.dev/subs
## Developer Documentation
| `ink_metadata` | `ink_env` | `ink_storage` | `ink_prelude` |
| ------------- | ------------- | ------------- | ------------- |
| [![][h1]][h2] | [![][g1]][g2] | [![][f1]][f2] | [![][i1]][i2] |
| `ink_metadata` | `ink_env` | `ink_storage` | `ink_lang` | `ink_prelude` |
| ------------- | ------------- | ------------- | ------------- | ------------- |
| [![][h1]][h2] | [![][g1]][g2] | [![][f1]][f2] | [![][j1]][j2] | [![][i1]][i2] |
### Interaction with Substrate
......
......@@ -513,7 +513,7 @@ where
}
/// Prints the given contents to the environmental log.
pub fn println(content: &str) {
pub fn debug_println(content: &str) {
<EnvInstance as OnInstance>::on_instance(|instance| Env::println(instance, content))
}
......
......@@ -23,17 +23,19 @@ use crate::{
CallParams,
CreateParams,
},
Blake2x128,
Blake2x256,
CryptoHash,
hash::{
Blake2x128,
Blake2x256,
CryptoHash,
HashOutput,
Keccak256,
Sha2x256,
},
Env,
EnvError,
EnvTypes,
HashOutput,
Keccak256,
Result,
ReturnFlags,
Sha2x256,
Topics,
TypedEnv,
};
......
......@@ -24,17 +24,19 @@ use crate::{
CallParams,
CreateParams,
},
Blake2x128,
Blake2x256,
CryptoHash,
hash::{
Blake2x128,
Blake2x256,
CryptoHash,
HashOutput,
Keccak256,
Sha2x256,
},
Env,
EnvError,
EnvTypes,
HashOutput,
Keccak256,
Result,
ReturnFlags,
Sha2x256,
Topics,
TypedEnv,
};
......
......@@ -86,14 +86,6 @@ pub use self::{
EnvError,
Result,
},
hash::{
Blake2x128,
Blake2x256,
CryptoHash,
HashOutput,
Keccak256,
Sha2x256,
},
types::{
AccountId,
Clear,
......
......@@ -19,6 +19,7 @@ use crate::DispatchError;
/// Tells the [`DispatchUsingMode`](`crate::DispatchUsingMode`) implementation for
/// an ink! smart contract how to dispatch for a call.
#[derive(Copy, Clone, PartialEq, Eq)]
#[doc(hidden)]
pub enum DispatchMode {
/// Mode for instantiating a contract.
Instantiate,
......@@ -29,6 +30,7 @@ pub enum DispatchMode {
/// Trait implemented by contracts themselves in order to provide a clean
/// interface for the C-ABI specified `call` and `create` functions to forward
/// calls to.
#[doc(hidden)]
pub trait DispatchUsingMode {
fn dispatch_using_mode(mode: DispatchMode) -> Result<(), DispatchError>;
}
......@@ -15,12 +15,14 @@
use ink_env::EnvTypes;
/// The type that can never be returned because it is not possible to craft an instance of it.
#[doc(hidden)]
pub enum NeverReturns {}
/// Implemented by contracts that are compiled as dependencies.
///
/// This allows to forward `&self` calls to a call forwarder
/// that encodes and dispatches the calls to the chain.
#[doc(hidden)]
pub trait ForwardCall {
/// The call forwarder that handles `&self` messages.
type Forwarder;
......@@ -33,6 +35,7 @@ pub trait ForwardCall {
///
/// This allows to forward `&mut self` calls to a call forwarder
/// that encodes and dispatches the calls to the chain.
#[doc(hidden)]
pub trait ForwardCallMut {
/// The call forwarder that handles `&mut self` messages.
type Forwarder;
......
......@@ -39,15 +39,18 @@ use ink_storage::{
};
/// Results of message handling operations.
#[doc(hidden)]
pub type Result<T> = core::result::Result<T, DispatchError>;
/// Connector trait: Connects enum dispatcher for messages with the contract.
#[doc(hidden)]
pub trait MessageDispatcher {
/// The contract's message dispatcher type.
type Type;
}
/// Connector trait: Connects enum dispatcher for constructors with the contract.
#[doc(hidden)]
pub trait ConstructorDispatcher {
/// The contract's constructors dispatcher type.
type Type;
......@@ -58,6 +61,7 @@ pub trait ConstructorDispatcher {
/// The generated message and constructor dispatch enums implement this trait
/// in order to forward their already decoded state to the selected messages
/// or constructors.
#[doc(hidden)]
pub trait Execute {
/// Starts the smart contract execution.
fn execute(self) -> Result<()>;
......@@ -65,6 +69,7 @@ pub trait Execute {
/// Yields `true` if the message accepts payments.
#[derive(Copy, Clone)]
#[doc(hidden)]
pub struct AcceptsPayments(pub bool);
impl From<AcceptsPayments> for bool {
......@@ -76,6 +81,7 @@ impl From<AcceptsPayments> for bool {
/// Yields `true` if the dynamic storage allocator is enabled for the given call.
#[derive(Copy, Clone)]
#[doc(hidden)]
pub struct EnablesDynamicStorageAllocator(pub bool);
impl From<EnablesDynamicStorageAllocator> for bool {
......@@ -92,6 +98,7 @@ impl From<EnablesDynamicStorageAllocator> for bool {
/// The closure is supposed to already contain all the arguments that the real
/// message requires and forwards them.
#[inline]
#[doc(hidden)]
pub fn execute_message<E, M, F>(
accepts_payments: AcceptsPayments,
enables_dynamic_storage_allocator: EnablesDynamicStorageAllocator,
......@@ -129,6 +136,7 @@ where
///
/// If the caller did send some amount of transferred value to the callee.
#[inline]
#[doc(hidden)]
pub fn deny_payment<E>() -> Result<()>
where
E: EnvTypes,
......@@ -148,6 +156,7 @@ where
/// The closure is supposed to already contain all the arguments that the real
/// message requires and forwards them.
#[inline]
#[doc(hidden)]
pub fn execute_message_mut<E, M, F>(
accepts_payments: AcceptsPayments,
enables_dynamic_storage_allocator: EnablesDynamicStorageAllocator,
......@@ -188,6 +197,7 @@ where
/// The closure is supposed to already contain all the arguments that the real
/// constructor message requires and forwards them.
#[inline]
#[doc(hidden)]
pub fn execute_constructor<C, F>(
enables_dynamic_storage_allocator: EnablesDynamicStorageAllocator,
f: F,
......
......@@ -19,6 +19,10 @@ use ink_env::{
CallParams,
CreateParams,
},
hash::{
CryptoHash,
HashOutput,
},
EnvTypes,
Result,
};
......@@ -143,22 +147,6 @@ where
ink_env::account_id::<T>().expect("couldn't decode contract account ID")
}
/// Returns the account ID of the executed contract.
///
/// # Note
///
/// - This functionality is deprecated. Please use [`EnvAccess::account_id`]
/// instead.
/// - For more details visit: [`ink_env::account_id`]
///
/// # Panics
///
/// If the returned value cannot be properly decoded.
#[deprecated(note = "please use self.env().account_id")]
pub fn address(self) -> T::AccountId {
ink_env::account_id::<T>().expect("couldn't decode contract account ID")
}
/// Returns the balance of the executed contract.
///
/// # Note
......@@ -281,10 +269,7 @@ where
/// # Note
///
/// For more details visit: [`ink_env::terminate_contract`]
pub fn terminate_contract(self, beneficiary: T::AccountId) -> !
where
T: EnvTypes,
{
pub fn terminate_contract(self, beneficiary: T::AccountId) -> ! {
ink_env::terminate_contract::<T>(beneficiary)
}
......@@ -293,10 +278,7 @@ where
/// # Note
///
/// For more details visit: [`ink_env::transfer`]
pub fn transfer(self, destination: T::AccountId, value: T::Balance) -> Result<()>
where
T: EnvTypes,
{
pub fn transfer(self, destination: T::AccountId, value: T::Balance) -> Result<()> {
ink_env::transfer::<T>(destination, value)
}
......@@ -305,10 +287,36 @@ where
/// # Note
///
/// For more details visit: [`ink_env::random`]
pub fn random(self, subject: &[u8]) -> T::Hash
pub fn random(self, subject: &[u8]) -> T::Hash {
ink_env::random::<T>(subject).expect("couldn't decode randomized hash")
}
/// Computes the hash of the given bytes using the cryptographic hash `H`.
///
/// # Note
///
/// For more details visit: [`ink_env::hash_bytes`]
pub fn hash_bytes<H>(self, input: &[u8]) -> <H as HashOutput>::Type
where
T: EnvTypes,
H: CryptoHash,
{
ink_env::random::<T>(subject).expect("couldn't decode randomized hash")
let mut output = <H as HashOutput>::Type::default();
ink_env::hash_bytes::<H>(input, &mut output);
output
}
/// Computes the hash of the given SCALE encoded value using the cryptographic hash `H`.
///
/// # Note
///
/// For more details visit: [`ink_env::hash_encoded`]
pub fn hash_encoded<H, V>(self, value: &V) -> <H as HashOutput>::Type
where
H: CryptoHash,
V: scale::Encode,
{
let mut output = <H as HashOutput>::Type::default();
ink_env::hash_encoded::<H, V>(value, &mut output);
output
}
}
......@@ -13,10 +13,12 @@
// limitations under the License.
/// A dispatch result.
#[doc(hidden)]
pub type DispatchResult = core::result::Result<(), DispatchError>;
/// A dispatch error.
#[derive(Debug, Copy, Clone)]
#[doc(hidden)]
pub enum DispatchError {
UnknownSelector,
UnknownInstantiateSelector,
......@@ -40,6 +42,7 @@ impl DispatchError {
/// A return code indicating success or error in a compact form.
#[derive(Copy, Clone)]
#[doc(hidden)]
pub struct DispatchRetCode(u32);
impl DispatchRetCode {
......
......@@ -37,8 +37,3 @@ pub trait BaseEvent {
/// The generated base event enum.
type Type;
}
/// Predicate types that evaluate to `true`.
pub trait True {}
/// Predicate types that evaluate to `false`.
pub trait False {}
......@@ -58,8 +58,6 @@ pub use self::{
events::{
BaseEvent,
EmitEvent,
False,
True,
},
traits::{
CheckedInkTrait,
......@@ -71,6 +69,7 @@ pub use self::{
ImpliesReturn,
MessageMut,
MessageRef,
True,
},
};
pub use ::static_assertions;
......
......@@ -28,10 +28,12 @@ use ink_storage::traits::SpreadLayout;
/// Trait used to indicate that an ink! trait definition has been checked
/// by the `#[ink::trait_definition]` proc. macro.
#[doc(hidden)]
pub unsafe trait CheckedInkTrait<T> {}
/// Trait used by `#[ink::trait_definition]` to ensure that the associated
/// return type for each trait message is correct.
#[doc(hidden)]
pub trait ImpliesReturn<T> {}
impl<T> ImpliesReturn<T> for T {}
......@@ -64,35 +66,41 @@ where
}
/// Dispatchable functions that have inputs.
#[doc(hidden)]
pub trait FnInput {
/// The tuple-type of all inputs.
type Input: scale::Decode + 'static;
}
/// Dispatchable functions that have an output.
#[doc(hidden)]
pub trait FnOutput {
/// The output type.
type Output: scale::Encode + 'static;
}
/// The selector of dispatchable functions.
#[doc(hidden)]
pub trait FnSelector {
/// The selector.
const SELECTOR: Selector;
}
/// The storage state that the dispatchable function acts on.
#[doc(hidden)]
pub trait FnState {
/// The storage state.
type State: SpreadLayout + Sized;
}
/// A dispatchable contract constructor message.
#[doc(hidden)]
pub trait Constructor: FnInput + FnSelector + FnState {
const CALLABLE: fn(<Self as FnInput>::Input) -> <Self as FnState>::State;
}
/// A `&self` dispatchable contract message.
#[doc(hidden)]
pub trait MessageRef: FnInput + FnOutput + FnSelector + FnState {
const CALLABLE: fn(
&<Self as FnState>::State,
......@@ -101,9 +109,14 @@ pub trait MessageRef: FnInput + FnOutput + FnSelector + FnState {
}
/// A `&mut self` dispatchable contract message.
#[doc(hidden)]
pub trait MessageMut: FnInput + FnOutput + FnSelector + FnState {
const CALLABLE: fn(
&mut <Self as FnState>::State,
<Self as FnInput>::Input,
) -> <Self as FnOutput>::Output;
}
/// Indicates that some compile time expression is expected to be `true`.
#[doc(hidden)]
pub trait True {}
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment