rgbstd/interface/
rgb20.rs

1// RGB standard library for working with smart contracts on Bitcoin & Lightning
2//
3// SPDX-License-Identifier: Apache-2.0
4//
5// Written in 2019-2023 by
6//     Dr Maxim Orlovsky <orlovsky@lnp-bp.org>
7//
8// Copyright (C) 2019-2023 LNP/BP Standards Association. All rights reserved.
9//
10// Licensed under the Apache License, Version 2.0 (the "License");
11// you may not use this file except in compliance with the License.
12// You may obtain a copy of the License at
13//
14//     http://www.apache.org/licenses/LICENSE-2.0
15//
16// Unless required by applicable law or agreed to in writing, software
17// distributed under the License is distributed on an "AS IS" BASIS,
18// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19// See the License for the specific language governing permissions and
20// limitations under the License.
21
22use amplify::confinement::LargeVec;
23use bp::bc::stl::bp_tx_stl;
24use strict_types::{CompileError, LibBuilder, TypeLib};
25
26use super::{
27    AssignIface, GenesisIface, GlobalIface, Iface, OwnedIface, Req, TransitionIface, VerNo,
28};
29use crate::interface::{ArgSpec, ContractIface, FungibleAllocation, OutpointFilter};
30use crate::stl::{
31    rgb_contract_stl, Amount, ContractData, DivisibleAssetSpec, StandardTypes, Timestamp,
32};
33
34pub const LIB_NAME_RGB20: &str = "RGB20";
35/// Strict types id for the library providing data types for RGB20 interface.
36pub const LIB_ID_RGB20: &str =
37    "urn:ubideco:stl:GVz4mvYE94aQ9q2HPtV9VuoppcDdduP54BMKffF7YoFH#prince-scarlet-ringo";
38
39const SUPPLY_MISMATCH: u8 = 1;
40const NON_EQUAL_AMOUNTS: u8 = 2;
41const INVALID_PROOF: u8 = 3;
42const INSUFFICIENT_RESERVES: u8 = 4;
43const INSUFFICIENT_COVERAGE: u8 = 5;
44const ISSUE_EXCEEDS_ALLOWANCE: u8 = 6;
45
46#[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
47#[derive(StrictType, StrictDumb, StrictEncode, StrictDecode)]
48#[strict_type(lib = LIB_NAME_RGB20, tags = repr, into_u8, try_from_u8)]
49#[repr(u8)]
50pub enum Error {
51    #[strict_type(dumb)]
52    SupplyMismatch = SUPPLY_MISMATCH,
53    NonEqualAmounts = NON_EQUAL_AMOUNTS,
54    InvalidProof = INVALID_PROOF,
55    InsufficientReserves = INSUFFICIENT_RESERVES,
56    InsufficientCoverage = INSUFFICIENT_COVERAGE,
57    IssueExceedsAllowance = ISSUE_EXCEEDS_ALLOWANCE,
58}
59
60fn _rgb20_stl() -> Result<TypeLib, CompileError> {
61    LibBuilder::new(libname!(LIB_NAME_RGB20), tiny_bset! {
62        bp_tx_stl().to_dependency(),
63        rgb_contract_stl().to_dependency()
64    })
65    .transpile::<Error>()
66    .compile()
67}
68
69/// Generates strict type library providing data types for RGB20 interface.
70pub fn rgb20_stl() -> TypeLib { _rgb20_stl().expect("invalid strict type RGB20 library") }
71
72pub fn rgb20() -> Iface {
73    let types = StandardTypes::with(rgb20_stl());
74
75    Iface {
76        version: VerNo::V1,
77        name: tn!("RGB20"),
78        global_state: tiny_bmap! {
79            fname!("spec") => GlobalIface::required(types.get("RGBContract.DivisibleAssetSpec")),
80            fname!("data") => GlobalIface::required(types.get("RGBContract.ContractData")),
81            fname!("created") => GlobalIface::required(types.get("RGBContract.Timestamp")),
82            fname!("issuedSupply") => GlobalIface::one_or_many(types.get("RGBContract.Amount")),
83            fname!("burnedSupply") => GlobalIface::none_or_many(types.get("RGBContract.Amount")),
84            fname!("replacedSupply") => GlobalIface::none_or_many(types.get("RGBContract.Amount")),
85        },
86        assignments: tiny_bmap! {
87            fname!("inflationAllowance") => AssignIface::public(OwnedIface::Amount, Req::NoneOrMore),
88            fname!("updateRight") => AssignIface::public(OwnedIface::Rights, Req::Optional),
89            fname!("burnEpoch") => AssignIface::public(OwnedIface::Rights, Req::Optional),
90            fname!("burnRight") => AssignIface::public(OwnedIface::Rights, Req::NoneOrMore),
91            fname!("assetOwner") => AssignIface::private(OwnedIface::Amount, Req::NoneOrMore),
92        },
93        valencies: none!(),
94        genesis: GenesisIface {
95            metadata: Some(types.get("RGBContract.IssueMeta")),
96            global: tiny_bmap! {
97                fname!("spec") => ArgSpec::required(),
98                fname!("data") => ArgSpec::required(),
99                fname!("created") => ArgSpec::required(),
100                fname!("issuedSupply") => ArgSpec::required(),
101            },
102            assignments: tiny_bmap! {
103                fname!("assetOwner") => ArgSpec::many(),
104                fname!("inflationAllowance") => ArgSpec::many(),
105                fname!("updateRight") => ArgSpec::optional(),
106                fname!("burnEpoch") => ArgSpec::optional(),
107            },
108            valencies: none!(),
109            errors: tiny_bset! {
110                SUPPLY_MISMATCH,
111                INVALID_PROOF,
112                INSUFFICIENT_RESERVES
113            },
114        },
115        transitions: tiny_bmap! {
116            tn!("Transfer") => TransitionIface {
117                optional: false,
118                metadata: None,
119                globals: none!(),
120                inputs: tiny_bmap! {
121                    fname!("previous") => ArgSpec::from_non_empty("assetOwner"),
122                },
123                assignments: tiny_bmap! {
124                    fname!("beneficiary") => ArgSpec::from_non_empty("assetOwner"),
125                },
126                valencies: none!(),
127                errors: tiny_bset! {
128                    NON_EQUAL_AMOUNTS
129                },
130                default_assignment: Some(fname!("beneficiary")),
131            },
132            tn!("Issue") => TransitionIface {
133                optional: true,
134                metadata: Some(types.get("RGBContract.IssueMeta")),
135                globals: tiny_bmap! {
136                    fname!("issuedSupply") => ArgSpec::required(),
137                },
138                inputs: tiny_bmap! {
139                    fname!("used") => ArgSpec::from_non_empty("inflationAllowance"),
140                },
141                assignments: tiny_bmap! {
142                    fname!("beneficiary") => ArgSpec::from_many("assetOwner"),
143                    fname!("future") => ArgSpec::from_many("inflationAllowance"),
144                },
145                valencies: none!(),
146                errors: tiny_bset! {
147                    SUPPLY_MISMATCH,
148                    INVALID_PROOF,
149                    ISSUE_EXCEEDS_ALLOWANCE,
150                    INSUFFICIENT_RESERVES
151                },
152                default_assignment: Some(fname!("beneficiary")),
153            },
154            tn!("OpenEpoch") => TransitionIface {
155                optional: true,
156                metadata: None,
157                globals: none!(),
158                inputs: tiny_bmap! {
159                    fname!("used") => ArgSpec::from_required("burnEpoch"),
160                },
161                assignments: tiny_bmap! {
162                    fname!("next") => ArgSpec::from_optional("burnEpoch"),
163                    fname!("burnRight") => ArgSpec::required()
164                },
165                valencies: none!(),
166                errors: none!(),
167                default_assignment: Some(fname!("burnRight")),
168            },
169            tn!("Burn") => TransitionIface {
170                optional: true,
171                metadata: Some(types.get("RGBContract.BurnMeta")),
172                globals: tiny_bmap! {
173                    fname!("burnedSupply") => ArgSpec::required(),
174                },
175                inputs: tiny_bmap! {
176                    fname!("used") => ArgSpec::from_required("burnRight"),
177                },
178                assignments: tiny_bmap! {
179                    fname!("future") => ArgSpec::from_optional("burnRight"),
180                },
181                valencies: none!(),
182                errors: tiny_bset! {
183                    SUPPLY_MISMATCH,
184                    INVALID_PROOF,
185                    INSUFFICIENT_COVERAGE
186                },
187                default_assignment: None,
188            },
189            tn!("Replace") => TransitionIface {
190                optional: true,
191                metadata: Some(types.get("RGBContract.BurnMeta")),
192                globals: tiny_bmap! {
193                    fname!("replacedSupply") => ArgSpec::required(),
194                },
195                inputs: tiny_bmap! {
196                    fname!("used") => ArgSpec::from_required("burnRight"),
197                },
198                assignments: tiny_bmap! {
199                    fname!("beneficiary") => ArgSpec::from_many("assetOwner"),
200                    fname!("future") => ArgSpec::from_optional("burnRight"),
201                },
202                valencies: none!(),
203                errors: tiny_bset! {
204                    NON_EQUAL_AMOUNTS,
205                    SUPPLY_MISMATCH,
206                    INVALID_PROOF,
207                    INSUFFICIENT_COVERAGE
208                },
209                default_assignment: Some(fname!("beneficiary")),
210            },
211            tn!("Rename") => TransitionIface {
212                optional: true,
213                metadata: None,
214                globals: tiny_bmap! {
215                    fname!("new") => ArgSpec::from_required("spec"),
216                },
217                inputs: tiny_bmap! {
218                    fname!("used") => ArgSpec::from_required("updateRight"),
219                },
220                assignments: tiny_bmap! {
221                    fname!("future") => ArgSpec::from_optional("updateRight"),
222                },
223                valencies: none!(),
224                errors: none!(),
225                default_assignment: Some(fname!("future")),
226            },
227        },
228        extensions: none!(),
229        error_type: types.get("RGB20.Error"),
230        default_operation: Some(tn!("Transfer")),
231        type_system: types.type_system(),
232    }
233}
234
235#[derive(Wrapper, WrapperMut, Clone, Eq, PartialEq, Debug)]
236#[wrapper(Deref)]
237#[wrapper_mut(DerefMut)]
238pub struct Rgb20(ContractIface);
239
240impl From<ContractIface> for Rgb20 {
241    fn from(iface: ContractIface) -> Self {
242        if iface.iface.iface_id != rgb20().iface_id() {
243            panic!("the provided interface is not RGB20 interface");
244        }
245        Self(iface)
246    }
247}
248
249impl Rgb20 {
250    pub fn spec(&self) -> DivisibleAssetSpec {
251        let strict_val = &self
252            .0
253            .global("spec")
254            .expect("RGB20 interface requires global state `spec`")[0];
255        DivisibleAssetSpec::from_strict_val_unchecked(strict_val)
256    }
257
258    pub fn created(&self) -> Timestamp {
259        let strict_val = &self
260            .0
261            .global("created")
262            .expect("RGB20 interface requires global state `created`")[0];
263        Timestamp::from_strict_val_unchecked(strict_val)
264    }
265
266    pub fn balance(&self, filter: &impl OutpointFilter) -> u64 {
267        self.allocations(filter)
268            .iter()
269            .map(|alloc| alloc.value)
270            .sum::<u64>()
271    }
272
273    pub fn allocations(&self, filter: &impl OutpointFilter) -> LargeVec<FungibleAllocation> {
274        self.0
275            .fungible("assetOwner", filter)
276            .expect("RGB20 interface requires `assetOwner` state")
277    }
278
279    pub fn contract_data(&self) -> ContractData {
280        let strict_val = &self
281            .0
282            .global("data")
283            .expect("RGB20 interface requires global `data`")[0];
284        ContractData::from_strict_val_unchecked(strict_val)
285    }
286
287    pub fn total_issued_supply(&self) -> Amount {
288        self.0
289            .global("issuedSupply")
290            .expect("RGB20 interface requires global `issuedSupply`")
291            .iter()
292            .map(Amount::from_strict_val_unchecked)
293            .sum()
294    }
295
296    pub fn total_burned_supply(&self) -> Amount {
297        self.0
298            .global("burnedSupply")
299            .unwrap_or_default()
300            .iter()
301            .map(Amount::from_strict_val_unchecked)
302            .sum()
303    }
304
305    pub fn total_replaced_supply(&self) -> Amount {
306        self.0
307            .global("replacedSupply")
308            .unwrap_or_default()
309            .iter()
310            .map(Amount::from_strict_val_unchecked)
311            .sum()
312    }
313
314    pub fn total_supply(&self) -> Amount { self.total_issued_supply() - self.total_burned_supply() }
315}
316
317#[cfg(test)]
318mod test {
319    use super::*;
320    use crate::containers::BindleContent;
321
322    const RGB20: &str = include_str!("../../tests/data/rgb20.rgba");
323
324    #[test]
325    fn lib_id() {
326        let lib = rgb20_stl();
327        assert_eq!(lib.id().to_string(), LIB_ID_RGB20);
328    }
329
330    #[test]
331    fn iface_creation() { rgb20(); }
332
333    #[test]
334    fn iface_bindle() {
335        assert_eq!(format!("{}", rgb20().bindle()), RGB20);
336    }
337}
rgbstd/interface/rgb20.rs

rgbstd/interface/
rgb20.rs
