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#[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
335pub 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}