Skip to main content

arete_hash/
idl.rs

1use arete_idl::{
2    normalize_idl_snapshot_v1, IdlAmountDecimalsSource, IdlAmountHint, IdlErrorSnapshot,
3    IdlSnapshotV1, IdlSpec, IdlType, IdlTypeArrayElement, IdlTypeDefinedInner,
4};
5use serde::{Deserialize, Serialize};
6use serde_json::Value;
7use std::collections::{BTreeMap, BTreeSet};
8
9use crate::{
10    canonicalize_jcs, hash_jcs, hash_raw_bytes, HashError, HashId, IdlContent, IdlNormalized,
11    IdlPortable, IdlSource, OssGeneratedProgramReleaseV1, ProgramRelease, ProgramSpec,
12};
13
14pub const PROGRAM_SPEC_SCHEMA_V1: &str = "arete.program-spec/v1";
15
16#[derive(Debug, Clone)]
17pub struct IdlHashes {
18    pub source: HashId<IdlSource>,
19    pub content: HashId<IdlContent>,
20    pub portable: HashId<IdlPortable>,
21    pub normalized: HashId<IdlNormalized>,
22}
23
24/// Strictly parsed IDL plus every authoritative v1 IDL projection.
25#[derive(Debug, Clone)]
26pub struct CanonicalIdlDocument {
27    source_bytes: Vec<u8>,
28    content: Value,
29    portable: Value,
30    idl: IdlSpec,
31    program_id: String,
32    snapshot: IdlSnapshotV1,
33    hashes: IdlHashes,
34}
35
36impl CanonicalIdlDocument {
37    pub fn parse(bytes: &[u8], explicit_program_id: Option<&str>) -> Result<Self, HashError> {
38        let mut content = crate::parse_json_bytes_strict(bytes)?;
39        let source_program_ids = collect_program_ids(&content)?;
40        let source_has_program_id = !source_program_ids.is_empty();
41        let program_id = resolve_program_id(source_program_ids, explicit_program_id)?;
42
43        if !source_has_program_id {
44            content
45                .as_object_mut()
46                .ok_or_else(|| HashError::InvalidIdl("IDL root must be an object".to_string()))?
47                .insert("address".to_string(), Value::String(program_id.clone()));
48        }
49
50        let parser_input = serde_json::to_string(&content)
51            .map_err(|error| HashError::Serialization(error.to_string()))?;
52        let mut idl =
53            arete_idl::parse::parse_idl_content(&parser_input).map_err(HashError::InvalidIdl)?;
54        idl.address = Some(program_id.clone());
55
56        let mut snapshot = normalize_idl_snapshot_v1(&idl);
57        snapshot.snapshot.program_id = Some(program_id.clone());
58        let portable = portable_idl_projection(&content)?;
59        let hashes = IdlHashes {
60            source: hash_raw_bytes(bytes)?,
61            content: hash_jcs(&content)?,
62            portable: hash_jcs(&portable)?,
63            normalized: hash_jcs(&snapshot)?,
64        };
65
66        Ok(Self {
67            source_bytes: bytes.to_vec(),
68            content,
69            portable,
70            idl,
71            program_id,
72            snapshot,
73            hashes,
74        })
75    }
76
77    pub fn source_bytes(&self) -> &[u8] {
78        &self.source_bytes
79    }
80
81    pub fn content_projection(&self) -> &Value {
82        &self.content
83    }
84
85    pub fn portable_projection(&self) -> &Value {
86        &self.portable
87    }
88
89    pub fn parsed_idl(&self) -> &IdlSpec {
90        &self.idl
91    }
92
93    pub fn program_id(&self) -> &str {
94        &self.program_id
95    }
96
97    pub fn normalized_snapshot(&self) -> &IdlSnapshotV1 {
98        &self.snapshot
99    }
100
101    pub fn hashes(&self) -> &IdlHashes {
102        &self.hashes
103    }
104
105    pub fn content_payload(&self) -> Result<Vec<u8>, HashError> {
106        canonicalize_jcs(&self.content)
107    }
108
109    pub fn portable_payload(&self) -> Result<Vec<u8>, HashError> {
110        canonicalize_jcs(&self.portable)
111    }
112
113    pub fn normalized_payload(&self) -> Result<Vec<u8>, HashError> {
114        canonicalize_jcs(&self.snapshot)
115    }
116}
117
118pub fn portable_idl_projection(source: &Value) -> Result<Value, HashError> {
119    let mut portable = source.clone();
120    let object = portable
121        .as_object_mut()
122        .ok_or_else(|| HashError::InvalidIdl("IDL root must be an object".to_string()))?;
123    object.remove("address");
124    object.remove("program_id");
125    if let Some(metadata) = object.get_mut("metadata").and_then(Value::as_object_mut) {
126        metadata.remove("address");
127    }
128    if let Some(program) = object.get_mut("program").and_then(Value::as_object_mut) {
129        program.remove("publicKey");
130    }
131    Ok(portable)
132}
133
134fn collect_program_ids(value: &Value) -> Result<Vec<(&'static str, String)>, HashError> {
135    let object = value
136        .as_object()
137        .ok_or_else(|| HashError::InvalidIdl("IDL root must be an object".to_string()))?;
138    let mut values = Vec::new();
139    collect_program_id(&mut values, "address", object.get("address"))?;
140    collect_program_id(&mut values, "program_id", object.get("program_id"))?;
141    collect_nested_program_id(
142        &mut values,
143        "metadata.address",
144        object.get("metadata"),
145        "address",
146    )?;
147    collect_nested_program_id(
148        &mut values,
149        "program.publicKey",
150        object.get("program"),
151        "publicKey",
152    )?;
153    Ok(values)
154}
155
156fn collect_nested_program_id(
157    output: &mut Vec<(&'static str, String)>,
158    location: &'static str,
159    parent: Option<&Value>,
160    key: &str,
161) -> Result<(), HashError> {
162    match parent {
163        None | Some(Value::Null) => Ok(()),
164        Some(Value::Object(object)) => collect_program_id(output, location, object.get(key)),
165        Some(_) => Err(HashError::InvalidProgramIdLocation { location }),
166    }
167}
168
169fn collect_program_id(
170    output: &mut Vec<(&'static str, String)>,
171    location: &'static str,
172    value: Option<&Value>,
173) -> Result<(), HashError> {
174    match value {
175        None | Some(Value::Null) => Ok(()),
176        Some(Value::String(value)) if value.is_empty() => Ok(()),
177        Some(Value::String(value)) => {
178            output.push((location, value.clone()));
179            Ok(())
180        }
181        Some(_) => Err(HashError::InvalidProgramIdLocation { location }),
182    }
183}
184
185fn resolve_program_id(
186    mut values: Vec<(&'static str, String)>,
187    explicit: Option<&str>,
188) -> Result<String, HashError> {
189    if let Some(explicit) = explicit {
190        if explicit.is_empty() {
191            return Err(HashError::MissingProgramId);
192        }
193        values.push(("explicit", explicit.to_string()));
194    }
195    if values.is_empty() {
196        return Err(HashError::MissingProgramId);
197    }
198
199    let distinct: BTreeSet<&str> = values.iter().map(|(_, value)| value.as_str()).collect();
200    if distinct.len() != 1 {
201        let detail = values
202            .iter()
203            .map(|(location, value)| format!("{location}={value}"))
204            .collect::<Vec<_>>()
205            .join(", ");
206        return Err(HashError::ConflictingProgramIds(detail));
207    }
208    Ok(values.remove(0).1)
209}
210
211#[derive(Debug, Clone, Serialize, Deserialize)]
212#[serde(rename_all = "camelCase")]
213pub struct ProgramSpecV1 {
214    pub schema: String,
215    pub program_id: String,
216    pub idl_content_hash: HashId<IdlContent>,
217    pub portable_idl_hash: HashId<IdlPortable>,
218    pub normalized_idl_hash: HashId<IdlNormalized>,
219    pub idl_snapshot: IdlSnapshotV1,
220    pub pdas: BTreeMap<String, PdaDefinitionV1>,
221    pub instructions: Vec<InstructionDefinitionV1>,
222}
223
224impl ProgramSpecV1 {
225    pub fn from_document(document: &CanonicalIdlDocument) -> Self {
226        let pdas = extract_pdas(document.parsed_idl());
227        let instructions =
228            extract_instructions(document.parsed_idl(), &pdas, document.program_id());
229        Self {
230            schema: PROGRAM_SPEC_SCHEMA_V1.to_string(),
231            program_id: document.program_id.clone(),
232            idl_content_hash: document.hashes.content,
233            portable_idl_hash: document.hashes.portable,
234            normalized_idl_hash: document.hashes.normalized,
235            idl_snapshot: document.snapshot.clone(),
236            pdas,
237            instructions,
238        }
239    }
240
241    pub fn hash(&self) -> Result<HashId<ProgramSpec>, HashError> {
242        self.validate()?;
243        hash_jcs(self)
244    }
245
246    pub fn validate(&self) -> Result<(), HashError> {
247        if self.schema != PROGRAM_SPEC_SCHEMA_V1 {
248            return Err(HashError::UnknownVersion(self.schema.clone()));
249        }
250        if self.idl_snapshot.normalization_version != arete_idl::IDL_NORMALIZATION_VERSION {
251            return Err(HashError::UnknownVersion(format!(
252                "IDL normalization version {}",
253                self.idl_snapshot.normalization_version
254            )));
255        }
256        if self.program_id.is_empty() {
257            return Err(HashError::MissingProgramId);
258        }
259        if self.idl_snapshot.snapshot.program_id.as_deref() != Some(self.program_id.as_str()) {
260            return Err(HashError::InvalidProjection {
261                projection: "program spec",
262                reason: "programId must match idlSnapshot.program_id".to_string(),
263            });
264        }
265        Ok(())
266    }
267
268    pub fn oss_release(&self) -> Result<OssGeneratedProgramReleaseV1, HashError> {
269        Ok(OssGeneratedProgramReleaseV1::new(
270            self.program_id.clone(),
271            self.hash()?,
272            self.idl_content_hash,
273            self.normalized_idl_hash,
274        ))
275    }
276
277    pub fn oss_release_hash(&self) -> Result<HashId<crate::ProgramRelease>, HashError> {
278        self.oss_release()?.hash()
279    }
280
281    pub fn oss_identity(&self) -> Result<OssProgramIdentityV1, HashError> {
282        OssProgramIdentityV1::new(self.clone())
283    }
284}
285
286#[derive(Debug, Clone)]
287pub struct OssProgramIdentityV1 {
288    pub program_spec: ProgramSpecV1,
289    pub program_spec_hash: HashId<ProgramSpec>,
290    pub release: OssGeneratedProgramReleaseV1,
291    pub release_hash: HashId<ProgramRelease>,
292}
293
294impl OssProgramIdentityV1 {
295    pub fn new(program_spec: ProgramSpecV1) -> Result<Self, HashError> {
296        let program_spec_hash = program_spec.hash()?;
297        let release = OssGeneratedProgramReleaseV1::new(
298            program_spec.program_id.clone(),
299            program_spec_hash,
300            program_spec.idl_content_hash,
301            program_spec.normalized_idl_hash,
302        );
303        let release_hash = release.hash()?;
304        Ok(Self {
305            program_spec,
306            program_spec_hash,
307            release,
308            release_hash,
309        })
310    }
311
312    pub fn from_document(document: &CanonicalIdlDocument) -> Result<Self, HashError> {
313        Self::new(ProgramSpecV1::from_document(document))
314    }
315}
316
317pub fn build_program_spec_v1_from_bytes(
318    bytes: &[u8],
319    explicit_program_id: Option<&str>,
320) -> Result<ProgramSpecV1, HashError> {
321    let document = CanonicalIdlDocument::parse(bytes, explicit_program_id)?;
322    Ok(ProgramSpecV1::from_document(&document))
323}
324
325pub fn build_oss_program_identity_v1_from_bytes(
326    bytes: &[u8],
327    explicit_program_id: Option<&str>,
328) -> Result<OssProgramIdentityV1, HashError> {
329    OssProgramIdentityV1::new(build_program_spec_v1_from_bytes(
330        bytes,
331        explicit_program_id,
332    )?)
333}
334
335/// Compatibility adapter for callers that no longer have the original bytes.
336///
337/// New ingress should always call `build_program_spec_v1_from_bytes` so
338/// `idl-content` is derived from the complete parsed source document.
339pub fn build_program_spec_v1_from_idl(
340    idl: &IdlSpec,
341    explicit_program_id: Option<&str>,
342) -> Result<ProgramSpecV1, HashError> {
343    let bytes =
344        serde_json::to_vec(idl).map_err(|error| HashError::Serialization(error.to_string()))?;
345    build_program_spec_v1_from_bytes(&bytes, explicit_program_id)
346}
347
348#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
349pub struct PdaDefinitionV1 {
350    pub name: String,
351    pub seeds: Vec<PdaSeedV1>,
352    #[serde(default, skip_serializing_if = "Option::is_none")]
353    pub program_id: Option<String>,
354}
355
356#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
357#[serde(tag = "type", rename_all = "camelCase")]
358pub enum PdaSeedV1 {
359    Literal {
360        value: String,
361    },
362    Bytes {
363        value: Vec<u8>,
364    },
365    ArgRef {
366        arg_name: String,
367        #[serde(default, skip_serializing_if = "Option::is_none")]
368        arg_type: Option<String>,
369    },
370    AccountRef {
371        account_name: String,
372    },
373}
374
375#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
376#[serde(tag = "category", rename_all = "camelCase")]
377pub enum AccountResolutionV1 {
378    Signer,
379    Known {
380        address: String,
381    },
382    PdaRef {
383        pda_name: String,
384    },
385    PdaInline {
386        seeds: Vec<PdaSeedV1>,
387        #[serde(default, skip_serializing_if = "Option::is_none")]
388        program_id: Option<String>,
389    },
390    UserProvided,
391}
392
393#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
394pub struct InstructionAccountV1 {
395    pub name: String,
396    #[serde(default)]
397    pub is_signer: bool,
398    #[serde(default)]
399    pub is_writable: bool,
400    pub resolution: AccountResolutionV1,
401    #[serde(default)]
402    pub is_optional: bool,
403    #[serde(default, skip_serializing_if = "Vec::is_empty")]
404    pub docs: Vec<String>,
405}
406
407#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
408#[serde(rename_all = "camelCase")]
409pub struct InstructionAmountHintV1 {
410    pub decimals_source: AmountDecimalsSourceV1,
411}
412
413#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
414#[serde(
415    tag = "kind",
416    rename_all = "camelCase",
417    rename_all_fields = "camelCase"
418)]
419pub enum AmountDecimalsSourceV1 {
420    ArgMint { arg_name: String },
421    ArgDecimals { arg_name: String },
422    KnownAccount { account_name: String },
423    Constant { decimals: u8 },
424}
425
426#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
427pub struct InstructionArgumentV1 {
428    pub name: String,
429    #[serde(rename = "type")]
430    pub arg_type: String,
431    #[serde(default, skip_serializing_if = "Vec::is_empty")]
432    pub docs: Vec<String>,
433    #[serde(default, skip_serializing_if = "Option::is_none")]
434    pub amount_hint: Option<InstructionAmountHintV1>,
435}
436
437fn default_discriminator_size() -> usize {
438    8
439}
440
441#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
442pub struct InstructionDefinitionV1 {
443    pub name: String,
444    pub discriminator: Vec<u8>,
445    #[serde(default = "default_discriminator_size")]
446    pub discriminator_size: usize,
447    pub accounts: Vec<InstructionAccountV1>,
448    pub args: Vec<InstructionArgumentV1>,
449    #[serde(default, skip_serializing_if = "Vec::is_empty")]
450    pub errors: Vec<IdlErrorSnapshot>,
451    #[serde(default, skip_serializing_if = "Option::is_none")]
452    pub program_id: Option<String>,
453    #[serde(default, skip_serializing_if = "Vec::is_empty")]
454    pub docs: Vec<String>,
455}
456
457fn extract_pdas(idl: &IdlSpec) -> BTreeMap<String, PdaDefinitionV1> {
458    let mut pdas = BTreeMap::new();
459    for pda in &idl.pdas {
460        let name = sanitize_identifier(&pda.name);
461        pdas.insert(
462            name.clone(),
463            convert_pda(&name, &pda.seeds, pda.program.as_ref()),
464        );
465    }
466    for instruction in &idl.instructions {
467        for account in instruction.flattened_accounts() {
468            if let Some(pda) = &account.pda {
469                let name = sanitize_identifier(pda.name.as_deref().unwrap_or(&account.name));
470                pdas.entry(name.clone())
471                    .or_insert_with(|| convert_pda(&name, &pda.seeds, pda.program.as_ref()));
472            }
473        }
474    }
475    pdas
476}
477
478fn extract_instructions(
479    idl: &IdlSpec,
480    pdas: &BTreeMap<String, PdaDefinitionV1>,
481    program_id: &str,
482) -> Vec<InstructionDefinitionV1> {
483    let uses_steel = idl.instructions.iter().any(|instruction| {
484        instruction.discriminant.is_some() && instruction.discriminator.is_empty()
485    });
486    let discriminator_size = if uses_steel { 1 } else { 8 };
487
488    idl.instructions
489        .iter()
490        .map(|instruction| InstructionDefinitionV1 {
491            name: instruction.name.clone(),
492            discriminator: instruction.get_discriminator(),
493            discriminator_size,
494            accounts: instruction
495                .flattened_accounts()
496                .iter()
497                .map(|account| convert_account(account, pdas))
498                .collect(),
499            args: instruction
500                .args
501                .iter()
502                .map(|argument| InstructionArgumentV1 {
503                    name: argument.name.clone(),
504                    arg_type: idl_type_to_rust_string(&argument.type_),
505                    docs: Vec::new(),
506                    amount_hint: argument.amount_hint.as_ref().map(convert_amount_hint),
507                })
508                .collect(),
509            errors: Vec::new(),
510            program_id: Some(program_id.to_string()),
511            docs: instruction.docs.clone(),
512        })
513        .collect()
514}
515
516fn convert_pda(
517    name: &str,
518    seeds: &[arete_idl::IdlPdaSeed],
519    program: Option<&arete_idl::IdlPdaProgram>,
520) -> PdaDefinitionV1 {
521    let seeds = seeds
522        .iter()
523        .map(|seed| match seed {
524            arete_idl::IdlPdaSeed::Const { value } => {
525                if let Ok(value) = String::from_utf8(value.clone()) {
526                    PdaSeedV1::Literal { value }
527                } else {
528                    PdaSeedV1::Bytes {
529                        value: value.clone(),
530                    }
531                }
532            }
533            arete_idl::IdlPdaSeed::Account { path, .. } => PdaSeedV1::AccountRef {
534                account_name: sanitize_seed_path(path),
535            },
536            arete_idl::IdlPdaSeed::Arg { path, arg_type } => PdaSeedV1::ArgRef {
537                arg_name: sanitize_seed_path(path),
538                arg_type: arg_type.clone(),
539            },
540        })
541        .collect();
542    let program_id = program.and_then(|program| match program {
543        arete_idl::IdlPdaProgram::Literal { value, .. } => Some(value.clone()),
544        arete_idl::IdlPdaProgram::Const { value, .. } => Some(bs58::encode(value).into_string()),
545        arete_idl::IdlPdaProgram::Account { .. } => None,
546    });
547    PdaDefinitionV1 {
548        name: name.to_string(),
549        seeds,
550        program_id,
551    }
552}
553
554fn convert_account(
555    account: &arete_idl::IdlAccountArg,
556    pdas: &BTreeMap<String, PdaDefinitionV1>,
557) -> InstructionAccountV1 {
558    let resolution = if account.is_signer && account.address.is_none() && account.pda.is_none() {
559        AccountResolutionV1::Signer
560    } else if let Some(address) = &account.address {
561        AccountResolutionV1::Known {
562            address: address.clone(),
563        }
564    } else if let Some(pda) = &account.pda {
565        let name = sanitize_identifier(pda.name.as_deref().unwrap_or(&account.name));
566        if pdas.contains_key(&name) {
567            AccountResolutionV1::PdaRef { pda_name: name }
568        } else {
569            let pda = convert_pda(&name, &pda.seeds, pda.program.as_ref());
570            AccountResolutionV1::PdaInline {
571                seeds: pda.seeds,
572                program_id: pda.program_id,
573            }
574        }
575    } else {
576        let name = sanitize_identifier(&account.name);
577        if pdas.contains_key(&name) {
578            AccountResolutionV1::PdaRef { pda_name: name }
579        } else {
580            AccountResolutionV1::UserProvided
581        }
582    };
583    InstructionAccountV1 {
584        name: sanitize_identifier(&account.name),
585        is_signer: account.is_signer,
586        is_writable: account.is_mut,
587        resolution,
588        is_optional: account.optional,
589        docs: account.docs.clone(),
590    }
591}
592
593fn convert_amount_hint(hint: &IdlAmountHint) -> InstructionAmountHintV1 {
594    InstructionAmountHintV1 {
595        decimals_source: match &hint.decimals_source {
596            IdlAmountDecimalsSource::ArgMint { arg_name } => AmountDecimalsSourceV1::ArgMint {
597                arg_name: arg_name.clone(),
598            },
599            IdlAmountDecimalsSource::ArgDecimals { arg_name } => {
600                AmountDecimalsSourceV1::ArgDecimals {
601                    arg_name: arg_name.clone(),
602                }
603            }
604            IdlAmountDecimalsSource::KnownAccount { account_name } => {
605                AmountDecimalsSourceV1::KnownAccount {
606                    account_name: account_name.clone(),
607                }
608            }
609            IdlAmountDecimalsSource::Constant { decimals } => AmountDecimalsSourceV1::Constant {
610                decimals: *decimals,
611            },
612        },
613    }
614}
615
616fn sanitize_identifier(name: &str) -> String {
617    let mut sanitized = String::new();
618    for character in name.chars() {
619        if character.is_ascii_alphanumeric() || character == '_' {
620            sanitized.push(character);
621        } else if !sanitized.ends_with('_') {
622            sanitized.push('_');
623        }
624    }
625    let sanitized = sanitized.trim_matches('_').to_string();
626    if sanitized.is_empty() {
627        return "value".to_string();
628    }
629    if sanitized
630        .chars()
631        .next()
632        .is_some_and(|character| character.is_ascii_digit())
633    {
634        return format!("_{sanitized}");
635    }
636    sanitized
637}
638
639fn sanitize_seed_path(path: &str) -> String {
640    path.split('.')
641        .map(sanitize_identifier)
642        .collect::<Vec<_>>()
643        .join(".")
644}
645
646fn idl_type_to_rust_string(idl_type: &IdlType) -> String {
647    match idl_type {
648        IdlType::Simple(simple) => match simple.as_str() {
649            "string" => "String".to_string(),
650            "publicKey" | "pubkey" => "solana_pubkey::Pubkey".to_string(),
651            "bytes" => "Vec<u8>".to_string(),
652            other => other.to_string(),
653        },
654        IdlType::Array(array) if array.array.len() == 2 => {
655            match (&array.array[0], &array.array[1]) {
656                (IdlTypeArrayElement::Type(name), IdlTypeArrayElement::Size(size)) => {
657                    format!(
658                        "[{}; {size}]",
659                        idl_type_to_rust_string(&IdlType::Simple(name.clone()))
660                    )
661                }
662                (IdlTypeArrayElement::Nested(ty), IdlTypeArrayElement::Size(size)) => {
663                    format!("[{}; {size}]", idl_type_to_rust_string(ty))
664                }
665                _ => "Vec<u8>".to_string(),
666            }
667        }
668        IdlType::Array(_) => "Vec<u8>".to_string(),
669        IdlType::Option(option) => format!("Option<{}>", idl_type_to_rust_string(&option.option)),
670        IdlType::Vec(vec_type) => format!("Vec<{}>", idl_type_to_rust_string(&vec_type.vec)),
671        IdlType::HashMap(hash_map) => format!(
672            "std::collections::HashMap<{}, {}>",
673            idl_type_to_rust_string(&hash_map.hash_map.0),
674            idl_type_to_rust_string(&hash_map.hash_map.1)
675        ),
676        IdlType::Defined(defined) => match &defined.defined {
677            IdlTypeDefinedInner::Named { name } => name.clone(),
678            IdlTypeDefinedInner::Simple(simple) => simple.clone(),
679        },
680    }
681}