templar_common/
registry.rs

1use near_sdk::{
2    json_types::{Base58CryptoHash, Base64VecU8, U64},
3    near, AccountId,
4};
5
6/// Delegated registry authority; Owner bypasses action guards without a synthetic membership.
7#[derive(Debug, Clone, Copy, PartialEq, Eq, near_sdk::BorshStorageKey)]
8#[near(serializers = [json, borsh(use_discriminant = true)])]
9#[repr(u8)]
10pub enum Role {
11    Uploader = 0,
12    Deployer = 1,
13}
14
15/// Code approved by the Owner without including WASM bytes in the approval.
16#[derive(Debug, Clone, Copy, PartialEq, Eq)]
17#[near(serializers = [json])]
18pub enum ApprovedCode {
19    Uploaded(Base58CryptoHash),
20    Global(Base58CryptoHash),
21}
22
23/// Pending upload metadata; views never expose the stored WASM bytes.
24#[derive(Debug, Clone, PartialEq, Eq)]
25#[near(serializers = [json])]
26pub struct UploadInfo {
27    pub uploader: AccountId,
28    pub code_len: u32,
29}
30
31/// Store the wasm or publish it as a global contract — the only open question once the bytes are
32/// in hand, which is why `registry.addArtifactVersion` still takes this.
33///
34/// [`VersionSource`] supersedes it on the `add_version` wire, where a third answer (a hash for code
35/// already on chain) is possible and the bytes are not a given.
36#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
37#[near(serializers = [json, borsh])]
38pub enum DeployMode {
39    Normal,
40    GlobalHash,
41}
42
43/// Where a version's code comes from, as one value.
44///
45/// Supersedes the `(DeployMode, Vec<u8>)` pair, which admitted a combination that means nothing:
46/// `Normal` alongside bytes already published as a global contract. Modelled on
47/// [`crate::upgrade::UpgradeSource`], which draws the same distinction for the upgrade path.
48///
49/// Borsh tags are pinned via explicit discriminants (`use_discriminant`): `tmplrmgr` plan files
50/// persist these args as opaque borsh, so the tag must not track declaration order. Discriminants
51/// 0 and 1 match `DeployMode::Normal`/`GlobalHash`, and [`Base64VecU8`] is a transparent borsh
52/// newtype over `Vec<u8>` — so `(version_key, Stored(code))` is byte-identical to the older
53/// `(version_key, DeployMode::Normal, code)`. `borsh_is_wire_compatible_with_deploy_mode` pins this.
54#[derive(Debug, Clone, PartialEq, Eq)]
55#[near(serializers = [json, borsh(use_discriminant = true)])]
56#[repr(u8)]
57pub enum VersionSource {
58    /// WASM held in registry state; `deploy` copies it onto each account.
59    Stored(Base64VecU8) = 0,
60    /// WASM published as a new global contract; the registry keeps only the hash.
61    PublishGlobal(Base64VecU8) = 1,
62    /// A global contract already on chain, by code hash. No publish cost.
63    ExistingGlobal(Base58CryptoHash) = 2,
64}
65
66impl std::fmt::Display for DeployMode {
67    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
68        match self {
69            DeployMode::Normal => write!(f, "Normal"),
70            DeployMode::GlobalHash => write!(f, "GlobalHash"),
71        }
72    }
73}
74
75#[derive(Clone, Debug, PartialEq, Eq)]
76#[near(serializers = [borsh, json])]
77pub struct Deployment {
78    pub version_key: String,
79    pub code_hash: Base58CryptoHash,
80    pub block_height: U64,
81}
82
83/// Where a registered version's code lives, and whether `deploy` can still use it.
84///
85/// `remove_version` soft-deletes by clearing the stored blob but keeping the key, and a
86/// `GlobalHash` version never stores one — so "has code" cannot tell the two apart.
87#[derive(Clone, Copy, Debug, PartialEq, Eq)]
88#[near(serializers = [json])]
89pub enum VersionAvailability {
90    /// Held in registry state. `code_len` sizes a chunked read of it.
91    Stored { code_len: u32 },
92    /// A NEAR global contract, resolvable by [`VersionInfo::code_hash`].
93    Global,
94    /// `remove_version` cleared the blob; the key remains but `deploy` panics.
95    Removed,
96}
97
98impl VersionAvailability {
99    pub fn is_deployable(self) -> bool {
100        matches!(self, Self::Stored { .. } | Self::Global)
101    }
102}
103
104/// A registered version.
105#[derive(Clone, Copy, Debug, PartialEq, Eq)]
106#[near(serializers = [json])]
107pub struct VersionInfo {
108    /// `sha256` of the code, computed by the registry when the version was added — unlike the
109    /// digest embedded in a version key, which is a convention the registry does not enforce.
110    pub code_hash: Base58CryptoHash,
111    pub availability: VersionAvailability,
112}
113
114/// A name's entry in the deployment map.
115///
116/// `deploy` refuses any name already present, so `Reserved` blocks a deployment just as
117/// `Deployed` does — a distinction [`Deployment`] alone cannot carry.
118#[derive(Clone, Debug, PartialEq, Eq)]
119#[near(serializers = [json])]
120pub enum RegistryEntryView {
121    /// Claimed by an in-flight deploy that has not finalized.
122    Reserved,
123    Deployed(Deployment),
124}
125
126impl RegistryEntryView {
127    pub fn deployment(&self) -> Option<&Deployment> {
128        match self {
129            Self::Reserved => None,
130            Self::Deployed(deployment) => Some(deployment),
131        }
132    }
133}
134
135#[cfg(test)]
136mod tests {
137    use near_sdk::serde_json::{self, json};
138    use rstest::rstest;
139
140    use super::*;
141
142    fn deployment() -> Deployment {
143        Deployment {
144            version_key: "market@1.5.0".to_string(),
145            code_hash: Base58CryptoHash::from([7u8; 32]),
146            block_height: 42.into(),
147        }
148    }
149
150    #[rstest]
151    #[case(Role::Uploader, 0, r#""Uploader""#)]
152    #[case(Role::Deployer, 1, r#""Deployer""#)]
153    fn role_wire_format(#[case] role: Role, #[case] tag: u8, #[case] expected: &str) {
154        assert_eq!(near_sdk::borsh::to_vec(&role).unwrap(), [tag]);
155        assert_eq!(near_sdk::borsh::from_slice::<Role>(&[tag]).unwrap(), role);
156        assert_eq!(serde_json::to_string(&role).unwrap(), expected);
157        assert_eq!(serde_json::from_str::<Role>(expected).unwrap(), role);
158    }
159
160    #[rstest]
161    #[case(
162        ApprovedCode::Uploaded(Base58CryptoHash::from([7u8; 32])),
163        r#"{"version_key":"market@1.5.0","code":{"Uploaded":"US517G5965aydkZ46HS38QLi7UQiSojurfbQfKCELFx"}}"#,
164    )]
165    #[case(
166        ApprovedCode::Global(Base58CryptoHash::from([7u8; 32])),
167        r#"{"version_key":"market@1.5.0","code":{"Global":"US517G5965aydkZ46HS38QLi7UQiSojurfbQfKCELFx"}}"#,
168    )]
169    fn approved_code_wire_format(#[case] code: ApprovedCode, #[case] expected: &str) {
170        #[derive(Debug, PartialEq)]
171        #[near(serializers = [json])]
172        struct Approval {
173            version_key: String,
174            code: ApprovedCode,
175        }
176        let approval = Approval {
177            version_key: "market@1.5.0".to_string(),
178            code,
179        };
180        assert_eq!(serde_json::to_string(&approval).unwrap(), expected);
181        assert_eq!(
182            serde_json::from_str::<Approval>(expected).unwrap(),
183            approval
184        );
185    }
186
187    #[test]
188    fn upload_info_wire_format() {
189        let info = UploadInfo {
190            uploader: "uploader.near".parse().unwrap(),
191            code_len: 4,
192        };
193        let expected = r#"{"uploader":"uploader.near","code_len":4}"#;
194        assert_eq!(serde_json::to_string(&info).unwrap(), expected);
195        assert_eq!(serde_json::from_str::<UploadInfo>(expected).unwrap(), info);
196    }
197
198    #[rstest]
199    #[case(VersionAvailability::Stored { code_len: 521_039 }, json!({ "Stored": { "code_len": 521_039 } }))]
200    #[case(VersionAvailability::Global, json!("Global"))]
201    #[case(VersionAvailability::Removed, json!("Removed"))]
202    fn availability_wire_format(
203        #[case] availability: VersionAvailability,
204        #[case] expected: serde_json::Value,
205    ) {
206        assert_eq!(serde_json::to_value(availability).unwrap(), expected);
207        assert_eq!(
208            serde_json::from_value::<VersionAvailability>(expected).unwrap(),
209            availability,
210        );
211    }
212
213    /// A `GlobalHash` version stores no code yet deploys fine, so "has code" would report it
214    /// alongside a soft-deleted one.
215    #[rstest]
216    #[case(VersionAvailability::Stored { code_len: 1 }, true)]
217    #[case(VersionAvailability::Global, true)]
218    #[case(VersionAvailability::Removed, false)]
219    fn deployability(#[case] availability: VersionAvailability, #[case] expected: bool) {
220        assert_eq!(availability.is_deployable(), expected);
221    }
222
223    #[test]
224    fn version_info_round_trips() {
225        let info = VersionInfo {
226            code_hash: Base58CryptoHash::from([3u8; 32]),
227            availability: VersionAvailability::Stored { code_len: 128 },
228        };
229        let value = serde_json::to_value(info).unwrap();
230        assert_eq!(serde_json::from_value::<VersionInfo>(value).unwrap(), info);
231    }
232
233    /// The fold from `(DeployMode, Vec<u8>)` to one [`VersionSource`] must not move a byte, or
234    /// every 1.1.0+ registry already on chain stops accepting `add_version`.
235    #[rstest]
236    #[case(DeployMode::Normal, VersionSource::Stored(Base64VecU8(vec![0xde, 0xad])))]
237    #[case(DeployMode::GlobalHash, VersionSource::PublishGlobal(Base64VecU8(vec![0xde, 0xad])))]
238    fn borsh_is_wire_compatible_with_deploy_mode(
239        #[case] mode: DeployMode,
240        #[case] source: VersionSource,
241    ) {
242        let version_key = "market@1.5.0";
243        assert_eq!(
244            near_sdk::borsh::to_vec(&(version_key, &source)).unwrap(),
245            near_sdk::borsh::to_vec(&(version_key, mode, vec![0xdeu8, 0xad])).unwrap(),
246        );
247    }
248
249    /// Golden bytes for the persisted tags. Plan files hold these opaquely, so a discriminant that
250    /// shifted with declaration order would silently repoint an already-written plan.
251    #[rstest]
252    #[case(VersionSource::Stored(Base64VecU8(vec![0xaa])), vec![0, 1, 0, 0, 0, 0xaa])]
253    #[case(VersionSource::PublishGlobal(Base64VecU8(vec![0xaa])), vec![1, 1, 0, 0, 0, 0xaa])]
254    #[case(
255        VersionSource::ExistingGlobal(Base58CryptoHash::from([7u8; 32])),
256        [&[2u8][..], &[7u8; 32][..]].concat(),
257    )]
258    fn borsh_discriminants_are_stable(#[case] source: VersionSource, #[case] expected: Vec<u8>) {
259        assert_eq!(near_sdk::borsh::to_vec(&source).unwrap(), expected);
260    }
261
262    #[rstest]
263    #[case(VersionSource::Stored(Base64VecU8(vec![1, 2, 3])))]
264    #[case(VersionSource::PublishGlobal(Base64VecU8(vec![1, 2, 3])))]
265    #[case(VersionSource::ExistingGlobal(Base58CryptoHash::from([9u8; 32])))]
266    fn version_source_round_trips(#[case] source: VersionSource) {
267        let bytes = near_sdk::borsh::to_vec(&source).unwrap();
268        assert_eq!(
269            near_sdk::borsh::from_slice::<VersionSource>(&bytes).unwrap(),
270            source,
271        );
272        let value = serde_json::to_value(&source).unwrap();
273        assert_eq!(
274            serde_json::from_value::<VersionSource>(value).unwrap(),
275            source,
276        );
277    }
278
279    /// The exact log line an indexer parses. Flattening puts the payload's fields beside
280    /// `version_key`/`account_id`; a nested object would be a different wire format.
281    #[rstest]
282    #[case::version_added(
283        RegistryEvent::VersionAdded {
284            version_key: "market@1.5.0".to_string(),
285            info: VersionInfo {
286                code_hash: Base58CryptoHash::from([7u8; 32]),
287                availability: VersionAvailability::Stored { code_len: 300 },
288            },
289        },
290        r#"EVENT_JSON:{"standard":"templar-registry","version":"1.0.0","event":"version_added","data":{"version_key":"market@1.5.0","code_hash":"US517G5965aydkZ46HS38QLi7UQiSojurfbQfKCELFx","availability":{"Stored":{"code_len":300}}}}"#
291    )]
292    #[case::deployed(
293        RegistryEvent::Deployed {
294            account_id: "one.registry.near".parse().unwrap(),
295            deployment: deployment(),
296            deployer: Some("deployer.near".parse().unwrap()),
297            full_access_keys: Some(vec!["ed25519:5BGSaf6YjVm7565VzWQHNxoyEjwr3jUpRJSGjREvU9dB".parse().unwrap()]),
298        },
299        r#"EVENT_JSON:{"standard":"templar-registry","version":"1.1.0","event":"deployed","data":{"account_id":"one.registry.near","version_key":"market@1.5.0","code_hash":"US517G5965aydkZ46HS38QLi7UQiSojurfbQfKCELFx","block_height":"42","deployer":"deployer.near","full_access_keys":["ed25519:5BGSaf6YjVm7565VzWQHNxoyEjwr3jUpRJSGjREvU9dB"]}}"#
300    )]
301    #[case::deployed_without_keys(
302        RegistryEvent::Deployed {
303            account_id: "one.registry.near".parse().unwrap(),
304            deployment: deployment(),
305            deployer: Some("deployer.near".parse().unwrap()),
306            full_access_keys: Some(Vec::new()),
307        },
308        r#"EVENT_JSON:{"standard":"templar-registry","version":"1.1.0","event":"deployed","data":{"account_id":"one.registry.near","version_key":"market@1.5.0","code_hash":"US517G5965aydkZ46HS38QLi7UQiSojurfbQfKCELFx","block_height":"42","deployer":"deployer.near","full_access_keys":[]}}"#
309    )]
310    #[case::deployed_legacy_callback(
311        RegistryEvent::Deployed {
312            account_id: "one.registry.near".parse().unwrap(),
313            deployment: deployment(),
314            deployer: None,
315            full_access_keys: None,
316        },
317        r#"EVENT_JSON:{"standard":"templar-registry","version":"1.1.0","event":"deployed","data":{"account_id":"one.registry.near","version_key":"market@1.5.0","code_hash":"US517G5965aydkZ46HS38QLi7UQiSojurfbQfKCELFx","block_height":"42","deployer":null,"full_access_keys":null}}"#
318    )]
319    #[case::code_uploaded(
320        RegistryEvent::CodeUploaded {
321            code_hash: Base58CryptoHash::from([7u8; 32]),
322            uploader: "uploader.near".parse().unwrap(),
323            code_len: 4,
324        },
325        r#"EVENT_JSON:{"standard":"templar-registry","version":"1.0.0","event":"code_uploaded","data":{"code_hash":"US517G5965aydkZ46HS38QLi7UQiSojurfbQfKCELFx","uploader":"uploader.near","code_len":4}}"#
326    )]
327    #[case::upload_removed(
328        RegistryEvent::UploadRemoved {
329            code_hash: Base58CryptoHash::from([7u8; 32]),
330            uploader: "uploader.near".parse().unwrap(),
331        },
332        r#"EVENT_JSON:{"standard":"templar-registry","version":"1.0.0","event":"upload_removed","data":{"code_hash":"US517G5965aydkZ46HS38QLi7UQiSojurfbQfKCELFx","uploader":"uploader.near"}}"#
333    )]
334    #[case::role_granted(
335        RegistryEvent::RoleSet {
336            account_id: "uploader.near".parse().unwrap(),
337            role: Role::Uploader,
338            is_granted: true,
339        },
340        r#"EVENT_JSON:{"standard":"templar-registry","version":"1.0.0","event":"role_set","data":{"account_id":"uploader.near","role":"Uploader","is_granted":true}}"#
341    )]
342    #[case::role_revoked(
343        RegistryEvent::RoleSet {
344            account_id: "deployer.near".parse().unwrap(),
345            role: Role::Deployer,
346            is_granted: false,
347        },
348        r#"EVENT_JSON:{"standard":"templar-registry","version":"1.0.0","event":"role_set","data":{"account_id":"deployer.near","role":"Deployer","is_granted":false}}"#
349    )]
350    fn event_wire_format(#[case] event: RegistryEvent, #[case] expected: &str) {
351        near_sdk::testing_env!(near_sdk::test_utils::VMContextBuilder::new().build());
352        event.emit();
353        assert_eq!(near_sdk::test_utils::get_logs(), [expected]);
354    }
355
356    #[test]
357    fn reserved_is_distinguishable_from_deployed() {
358        let reserved = RegistryEntryView::Reserved;
359        assert_eq!(serde_json::to_value(&reserved).unwrap(), json!("Reserved"));
360        assert_eq!(reserved.deployment(), None);
361
362        let deployed = RegistryEntryView::Deployed(deployment());
363        assert_eq!(deployed.deployment(), Some(&deployment()));
364        assert_eq!(
365            serde_json::from_value::<RegistryEntryView>(serde_json::to_value(&deployed).unwrap())
366                .unwrap(),
367            deployed,
368        );
369    }
370}
371
372#[near(event_json(standard = "templar-registry"))]
373pub enum RegistryEvent {
374    /// A version became deployable: logged by `add_version` for stored code, and by its finalize
375    /// callback once a global contract is confirmed, never for one that turns out not to exist.
376    #[event_version("1.0.0")]
377    VersionAdded {
378        version_key: String,
379        #[serde(flatten)]
380        info: VersionInfo,
381    },
382    /// `remove_version` cleared a stored version's code. The key stays registered but `deploy`
383    /// refuses it.
384    #[event_version("1.0.0")]
385    VersionRemoved {
386        version_key: String,
387        code_hash: Base58CryptoHash,
388    },
389    /// A deployment's account was created and initialized, and the name now resolves to it.
390    /// Legacy in-flight finalizers emit null provenance because they did not carry it.
391    #[event_version("1.1.0")]
392    Deployed {
393        account_id: AccountId,
394        #[serde(flatten)]
395        deployment: Deployment,
396        deployer: Option<AccountId>,
397        full_access_keys: Option<Vec<near_sdk::PublicKey>>,
398    },
399    /// Code was stored pending Owner approval.
400    #[event_version("1.0.0")]
401    CodeUploaded {
402        code_hash: Base58CryptoHash,
403        uploader: AccountId,
404        code_len: u32,
405    },
406    /// A pending upload was removed and its storage credit released to the payer.
407    #[event_version("1.0.0")]
408    UploadRemoved {
409        code_hash: Base58CryptoHash,
410        uploader: AccountId,
411    },
412    /// A successful role setter, following the proxy oracle's historical role-set payload.
413    #[event_version("1.0.0")]
414    RoleSet {
415        account_id: AccountId,
416        role: Role,
417        is_granted: bool,
418    },
419}