dusk_core/
abi.rs

1// This Source Code Form is subject to the terms of the Mozilla Public
2// License, v. 2.0. If a copy of the MPL was not distributed with this
3// file, You can obtain one at http://mozilla.org/MPL/2.0/.
4//
5// Copyright (c) DUSK NETWORK. All rights reserved.
6
7//! The Application Binary Interface (ABI) for the Dusk network.
8
9pub use piecrust_uplink::{
10    ARGBUF_LEN, CONTRACT_ID_BYTES, ContractError, ContractId, Event,
11    StandardBufSerializer,
12};
13
14#[cfg(feature = "abi")]
15pub use self::host_queries::*;
16
17/// Enum storing the metadata identifiers.
18pub enum Metadata {}
19
20impl Metadata {
21    /// The chain-id of the network.
22    pub const CHAIN_ID: &'static str = "chain_id";
23    /// The current block-height.
24    pub const BLOCK_HEIGHT: &'static str = "block_height";
25    /// The sender of the transaction, if the transaction is public.
26    pub const PUBLIC_SENDER: &'static str = "public_sender";
27}
28
29/// Enum storing the available host-queries.
30pub enum Query {}
31
32impl Query {
33    /// Host-function name to compute the hash of some input-data.
34    pub const HASH: &'static str = "hash";
35    /// Host-function name to compute the poseidon-hash of some input-data.
36    pub const POSEIDON_HASH: &'static str = "poseidon_hash";
37    /// Host-function name to verify a plonk-proof.
38    pub const VERIFY_PLONK: &'static str = "verify_plonk";
39    /// Host-function name to verify a groth16-bn254 proof.
40    pub const VERIFY_GROTH16_BN254: &'static str = "verify_groth16_bn254";
41    /// Host-function name to verify a schnorr-signature.
42    pub const VERIFY_SCHNORR: &'static str = "verify_schnorr";
43    /// Host-function name to verify a bls-signature.
44    pub const VERIFY_BLS: &'static str = "verify_bls";
45    /// Host-function name to verify a bls-multisig.
46    pub const VERIFY_BLS_MULTISIG: &'static str = "verify_bls_multisig";
47    /// Host-function name to compute the keccak256 hash.
48    pub const KECCAK256: &'static str = "keccak256";
49    /// Host-function name to compute the sha256 hash.
50    pub const SHA256: &'static str = "sha256";
51    /// Host-function name to verify a KZG point-evaluation proof.
52    pub const VERIFY_KZG_PROOF: &'static str = "verify_kzg_proof";
53    /// Host-function name to recover a secp256k1 public key.
54    pub const SECP256K1_RECOVER: &'static str = "secp256k1_recover";
55}
56
57#[cfg(feature = "abi")]
58pub(crate) mod host_queries {
59    use alloc::vec::Vec;
60
61    use dusk_bytes::Serializable;
62    #[cfg(feature = "abi-debug")]
63    pub use piecrust_uplink::debug as piecrust_debug;
64    pub use piecrust_uplink::{
65        call, call_raw, call_raw_with_limit, call_with_limit, caller,
66        callstack, emit, emit_raw, feed, limit, self_id, spent, wrap_call,
67        wrap_call_unchecked, /* maybe use for our Transaction in
68                              * spend_and_execute */
69    };
70    use piecrust_uplink::{host_query, meta_data};
71
72    use crate::BlsScalar;
73    use crate::abi::{ContractId, Metadata, Query};
74    use crate::signatures::bls::{
75        MultisigSignature, PublicKey as BlsPublicKey, Signature as BlsSignature,
76    };
77    use crate::signatures::schnorr::{
78        PublicKey as SchnorrPublicKey, Signature as SchnorrSignature,
79    };
80
81    /// Compute the blake2b hash of the given bytes, returning the resulting
82    /// scalar. The output of the hasher is truncated (last nibble) to fit
83    /// onto a scalar.
84    #[must_use]
85    pub fn hash(bytes: Vec<u8>) -> BlsScalar {
86        host_query(Query::HASH, bytes)
87    }
88
89    /// Compute the poseidon hash of the given scalars
90    #[must_use]
91    pub fn poseidon_hash(scalars: Vec<BlsScalar>) -> BlsScalar {
92        host_query(Query::POSEIDON_HASH, scalars)
93    }
94
95    /// Verify that a Groth16 proof in the BN254 pairing is valid for a given
96    /// circuit and inputs.
97    ///
98    /// `proof` and `inputs` should be in compressed form, while `pvk`
99    /// uncompressed.
100    #[must_use]
101    pub fn verify_groth16_bn254(
102        pvk: Vec<u8>,
103        proof: Vec<u8>,
104        inputs: Vec<u8>,
105    ) -> bool {
106        host_query(Query::VERIFY_GROTH16_BN254, (pvk, proof, inputs))
107    }
108
109    /// Verify a Plonk proof is valid for a given circuit type and public inputs
110    #[must_use]
111    pub fn verify_plonk(
112        verifier_data: Vec<u8>,
113        proof: Vec<u8>,
114        public_inputs: Vec<BlsScalar>,
115    ) -> bool {
116        host_query(Query::VERIFY_PLONK, (verifier_data, proof, public_inputs))
117    }
118
119    /// Verify a schnorr signature is valid for the given public key and message
120    #[must_use]
121    pub fn verify_schnorr(
122        msg: BlsScalar,
123        pk: SchnorrPublicKey,
124        sig: SchnorrSignature,
125    ) -> bool {
126        host_query(Query::VERIFY_SCHNORR, (msg, pk, sig))
127    }
128
129    /// Verify a BLS signature is valid for the given public key and message
130    #[must_use]
131    pub fn verify_bls(
132        msg: Vec<u8>,
133        pk: BlsPublicKey,
134        sig: BlsSignature,
135    ) -> bool {
136        host_query(Query::VERIFY_BLS, (msg, pk, sig))
137    }
138
139    /// Verify a BLS signature is valid for the given public key and message
140    #[must_use]
141    pub fn verify_bls_multisig(
142        msg: Vec<u8>,
143        keys: Vec<BlsPublicKey>,
144        sig: MultisigSignature,
145    ) -> bool {
146        host_query(Query::VERIFY_BLS_MULTISIG, (msg, keys, sig))
147    }
148
149    /// Compute the keccak256 hash of the given bytes, returning the resulting
150    /// bytes.
151    #[must_use]
152    pub fn keccak256(bytes: Vec<u8>) -> [u8; 32] {
153        host_query(Query::KECCAK256, bytes)
154    }
155
156    /// Compute the sha256 hash of the given bytes, returning the resulting
157    /// bytes.
158    #[must_use]
159    pub fn sha256(bytes: Vec<u8>) -> [u8; 32] {
160        host_query(Query::SHA256, bytes)
161    }
162
163    /// Verify a KZG point-evaluation proof for a commitment and evaluation.
164    #[must_use]
165    pub fn verify_kzg_proof(
166        commitment: [u8; 48],
167        z: [u8; 32],
168        y: [u8; 32],
169        proof: [u8; 48],
170    ) -> bool {
171        host_query(Query::VERIFY_KZG_PROOF, (commitment, z, y, proof))
172    }
173
174    /// Recover a secp256k1 public key from a 32-byte message hash and
175    /// signature.
176    ///
177    /// Signature is expected as r(32) || s(32) || v(1), with v in {0,1,27,28}.
178    #[must_use]
179    pub fn secp256k1_recover(
180        msg_hash: [u8; 32],
181        sig: [u8; 65],
182    ) -> Option<[u8; 65]> {
183        host_query(Query::SECP256K1_RECOVER, (msg_hash, sig))
184    }
185
186    /// Get the chain ID.
187    ///
188    /// # Panics
189    /// Panics if the chain doesn't store a `u8` `CHAIN_ID` in the metadata.
190    #[must_use]
191    pub fn chain_id() -> u8 {
192        meta_data(Metadata::CHAIN_ID).unwrap()
193    }
194
195    /// Get the current block height.
196    ///
197    /// # Panics
198    /// Panics if the chain doesn't store a `u64` `BLOCK_HEIGHT` in the
199    /// metadata.
200    #[must_use]
201    pub fn block_height() -> u64 {
202        meta_data(Metadata::BLOCK_HEIGHT).unwrap()
203    }
204
205    /// Get the public sender of the ongoing tx. Returns `None` if the
206    /// transaction is shielded.
207    ///
208    /// # Panics
209    /// Panics if the chain doesn't store a `Option<BlsPublicKey>`
210    /// `PUBLIC_SENDER` in the metadata.
211    #[must_use]
212    pub fn public_sender() -> Option<BlsPublicKey> {
213        meta_data(Metadata::PUBLIC_SENDER)
214            .expect("moonlight sender metadata to be set")
215    }
216
217    /// Query owner of a given contract.
218    /// Returns none if contract is not found.
219    ///
220    /// # Panics
221    /// Panics if owner is not a valid public key (should never happen).
222    #[must_use]
223    pub fn owner(contract: ContractId) -> Option<BlsPublicKey> {
224        owner_raw(contract).map(|buf| {
225            BlsPublicKey::from_bytes(&buf)
226                .expect("Owner should deserialize correctly")
227        })
228    }
229
230    /// Query self owner of a given contract.
231    ///
232    /// # Panics
233    /// Panics if owner is not a valid public key (should never happen).
234    #[must_use]
235    pub fn self_owner() -> BlsPublicKey {
236        let buf = self_owner_raw();
237        BlsPublicKey::from_bytes(&buf)
238            .expect("Owner should deserialize correctly")
239    }
240
241    /// Query raw `to_bytes` serialization of the owner of a given contract.
242    #[must_use]
243    pub fn owner_raw(contract: ContractId) -> Option<[u8; BlsPublicKey::SIZE]> {
244        piecrust_uplink::owner(contract)
245    }
246
247    /// Query raw `to_bytes` serialization of the self owner.
248    #[must_use]
249    pub fn self_owner_raw() -> [u8; BlsPublicKey::SIZE] {
250        piecrust_uplink::self_owner()
251    }
252}
dusk_core/abi.rs

dusk_core/
abi.rs
