Add #[slot(raw = KEY)] to bind a typed storage field to a fixed external slot (e.g. EIP-1967) while preserving the view/mut gate

filip-parity · filip-parity · commit e810d53d36c0 · 2026-07-07T14:39:13.000+03:00
diff --git a/crates/pvm-contract-macros/src/codegen/abi_gen.rs b/crates/pvm-contract-macros/src/codegen/abi_gen.rs
@@ -78,9 +78,13 @@ fn storage_layout_helper(slot_fields: &[SlotField]) -> TokenStream {
 
     let layout_emits: Vec<TokenStream> = slot_fields
         .iter()
-        .map(|sf| {
-            let (slot_expr, offset_expr): (TokenStream, TokenStream) = match sf.slot {
+        .filter_map(|sf| {
+            let (slot_expr, offset_expr): (TokenStream, TokenStream) = match &sf.slot {
                 Slot::Explicit(n) => (quote! { #n }, quote! { 0u8 }),
+                // Raw external slots (e.g. EIP-1967) live outside solc's
+                // sequential storage layout — solc doesn't emit them in
+                // `storageLayout` either, so omit them here.
+                Slot::ExplicitRaw(_) => return None,
                 Slot::Auto => {
                     let const_ident =
                         quote::format_ident!("{}{}", super::contract::AUTO_SLOT_PREFIX, &sf.name);
@@ -95,12 +99,12 @@ fn storage_layout_helper(slot_fields: &[SlotField]) -> TokenStream {
                 quote! { "" },
             );
             let cfgs = &sf.cfg_attrs;
-            quote! {
+            Some(quote! {
                 #(#cfgs)*
                 {
                     #emit
                 }
-            }
+            })
         })
         .collect();
 
diff --git a/crates/pvm-contract-macros/src/codegen/contract.rs b/crates/pvm-contract-macros/src/codegen/contract.rs
@@ -8,7 +8,7 @@ use super::dispatch::{
     MethodInfo, RouteItems, StateMutability, boundary_size_check, generate_param_decoding,
     generate_revert_encoding_boundary, generate_router,
 };
-use super::storage_layout::extract_optional_slot_attr;
+use super::storage_layout::{SlotAttr, extract_optional_slot_attr};
 use crate::signature::{SolType, compute_selector};
 use crate::utils::{compute_function_signature, to_snake_case};
 
@@ -208,6 +208,13 @@ pub(super) enum Slot {
     /// (`PACKED_BYTES == 32`); sub-word types must use auto-numbering.
     /// See [`SlotField`] for the rationale.
     Explicit(u64),
+    /// Explicit `#[slot(raw = EXPR)]`: bind the field to a fixed,
+    /// externally-known 32-byte slot (e.g. an EIP-1967 proxy slot), outside the
+    /// compiler-assigned sequential range. Unlike numeric `#[slot(N)]` this
+    /// accepts sub-word types and places them right-aligned (`offset =
+    /// 32 - PACKED_BYTES`) to match solc, since a pseudo-random external slot
+    /// has no sibling fields to pack with.
+    ExplicitRaw(syn::Expr),
     /// Auto-numbered: position among auto-numbered fields is taken from
     /// declaration order during the slot-chain build. Packs sub-word
     /// siblings via `layout_step`.
@@ -262,11 +269,14 @@ fn auto_chain_fields(slot_fields: &[SlotField]) -> Vec<super::storage_layout::Ch
 }
 
 impl SlotField {
-    /// Explicit slot value, or `None` if auto-numbered.
+    /// Explicit *numeric* slot value, or `None` if auto-numbered or bound to a
+    /// raw external slot. Raw slots return `None` because they live outside the
+    /// compiler-assigned sequential range and don't participate in the
+    /// numeric overlap / full-slot-only checks.
     pub(super) fn explicit_slot(&self) -> Option<u64> {
         match self.slot {
             Slot::Explicit(n) => Some(n),
-            Slot::Auto => None,
+            Slot::ExplicitRaw(_) | Slot::Auto => None,
         }
     }
 }
@@ -1298,19 +1308,35 @@ pub fn expand_contract(args: ContractArgs, input: ItemMod) -> syn::Result<TokenS
             let name = &sf.name;
             let ty = &sf.ty;
             let cfgs = &sf.cfg_attrs;
-            let (slot_expr, offset_expr, alone_expr): (TokenStream, TokenStream, TokenStream) =
-                match sf.slot {
+            let (key_expr, offset_expr, alone_expr): (TokenStream, TokenStream, TokenStream) =
+                match &sf.slot {
                     // Explicit `#[slot(N)]` is restricted to full-slot types
                     // elsewhere in this file (`explicit_slot_full_slot_only_checks`).
                     // Full-slot components ignore `alone`, so the literal `true`
                     // is purely cosmetic — it would behave identically as `false`
                     // for `Mapping`/`Lazy<U256>`/etc.
-                    Slot::Explicit(n) => (quote! { #n }, quote! { 0u8 }, quote! { true }),
+                    Slot::Explicit(n) => (
+                        quote! { ::pvm_contract_sdk::StorageKey::from_slot(#n) },
+                        quote! { 0u8 },
+                        quote! { true },
+                    ),
+                    // `#[slot(raw = EXPR)]` binds the field to a fixed external
+                    // 32-byte slot. Sub-word types are placed right-aligned at
+                    // `32 - PACKED_BYTES` (matching solc), and `alone = true`
+                    // because a pseudo-random external slot has no sibling
+                    // sub-word fields to preserve on write.
+                    Slot::ExplicitRaw(expr) => (
+                        quote! { ::pvm_contract_sdk::StorageKey::from_raw(#expr) },
+                        quote! {
+                            (32 - <#ty as ::pvm_contract_sdk::StorageComponent>::PACKED_BYTES) as u8
+                        },
+                        quote! { true },
+                    ),
                     Slot::Auto => {
                         let const_ident = quote::format_ident!("{}{}", AUTO_SLOT_PREFIX, name);
                         let alone_ident = quote::format_ident!("{}{}", AUTO_ALONE_PREFIX, name);
                         (
-                            quote! { #const_ident.slot },
+                            quote! { ::pvm_contract_sdk::StorageKey::from_slot(#const_ident.slot) },
                             quote! { #const_ident.offset },
                             quote! { #alone_ident },
                         )
@@ -1319,7 +1345,7 @@ pub fn expand_contract(args: ContractArgs, input: ItemMod) -> syn::Result<TokenS
             quote! {
                 #(#cfgs)*
                 #name: <#ty as ::pvm_contract_sdk::StorageComponent>::new_at(
-                    ::pvm_contract_sdk::StorageKey::from_slot(#slot_expr),
+                    #key_expr,
                     #offset_expr,
                     #alone_expr,
                     host.clone(),
@@ -1853,7 +1879,7 @@ fn extract_slot_fields_from_struct(item_struct: &syn::ItemStruct) -> syn::Result
     struct Raw {
         name: Ident,
         ty: syn::Type,
-        explicit: Option<u64>,
+        explicit: Option<SlotAttr>,
         cfg_attrs: Vec<syn::Attribute>,
         original_field: syn::Field,
     }
@@ -1921,8 +1947,14 @@ fn extract_slot_fields_from_struct(item_struct: &syn::ItemStruct) -> syn::Result
 
     let mut fields = Vec::new();
     for raw in raws {
-        let slot = if let Some(n) = raw.explicit {
-            Slot::Explicit(n)
+        let slot = if let Some(attr) = raw.explicit {
+            match attr {
+                SlotAttr::Numeric(n) => Slot::Explicit(n),
+                // Raw external slots carry an unevaluated `[u8; 32]` expression;
+                // like numeric explicit slots they may carry `#[cfg]` (they don't
+                // shift any later field's slot), so no cfg gate here.
+                SlotAttr::Raw(expr) => Slot::ExplicitRaw(expr),
+            }
         } else {
             // Auto-numbered fields share a const chain across slot consts;
             // a #[cfg]-disabled field in the middle of the chain would break
@@ -3262,6 +3294,59 @@ mod tests {
         );
     }
 
+    #[test]
+    fn raw_slot_field_constructs_from_raw_key_right_aligned() {
+        let item: ItemMod = syn::parse_str(
+            r#"
+            mod my_proxy {
+                const IMPL_SLOT: [u8; 32] = [0u8; 32];
+                pub struct MyProxy {
+                    #[slot(raw = IMPL_SLOT)]
+                    impl_addr: Lazy<Address>,
+                }
+                impl MyProxy {
+                    #[pvm_contract_macros::constructor]
+                    pub fn new(&mut self) {}
+
+                    #[pvm_contract_macros::method]
+                    pub fn implementation(&self) -> Address {
+                        self.impl_addr.get()
+                    }
+                }
+            }
+        "#,
+        )
+        .unwrap();
+
+        let output = expand_contract(ContractArgs::default(), item)
+            .unwrap()
+            .to_string();
+
+        // Raw-slot fields bind to StorageKey::from_raw(EXPR), not from_slot.
+        assert!(
+            output.contains(":: StorageKey :: from_raw (IMPL_SLOT)"),
+            "raw slot field should pass StorageKey::from_raw(IMPL_SLOT).\n\
+             Expanded output:\n{output}"
+        );
+        assert!(
+            !output.contains("from_slot"),
+            "a raw-only contract should emit no from_slot calls.\n\
+             Expanded output:\n{output}"
+        );
+        // Sub-word types are placed right-aligned at 32 - PACKED_BYTES.
+        assert!(
+            output.contains("(32 - < Lazy < Address > as :: pvm_contract_sdk :: StorageComponent > :: PACKED_BYTES) as u8"),
+            "raw sub-word field should be right-aligned at 32 - PACKED_BYTES.\n\
+             Expanded output:\n{output}"
+        );
+        // The #[slot(raw = ...)] attribute must be stripped from the struct.
+        assert!(
+            !output.contains("# [slot"),
+            "Slot attributes should be stripped from the struct output.\n\
+             Expanded output:\n{output}"
+        );
+    }
+
     #[test]
     fn slot_fields_initialize_in_deploy_and_call() {
         let item: ItemMod = syn::parse_str(
diff --git a/crates/pvm-contract-macros/src/codegen/storage_layout.rs b/crates/pvm-contract-macros/src/codegen/storage_layout.rs
@@ -181,9 +181,21 @@ pub(super) fn generate_layout_emit(
     }
 }
 
-/// Extract the `#[slot(N)]` attribute value from a field, if present.
+/// A parsed `#[slot(...)]` attribute value.
+#[derive(Debug, Clone)]
+pub(super) enum SlotAttr {
+    /// `#[slot(N)]` — a numeric slot index in the compiler-assigned range.
+    Numeric(u64),
+    /// `#[slot(raw = EXPR)]` — bind the field to a fixed, externally-known
+    /// 32-byte slot (e.g. an EIP-1967 proxy slot). `EXPR` must evaluate to a
+    /// `[u8; 32]`; it is quoted verbatim into the field initializer.
+    Raw(syn::Expr),
+}
+
+/// Extract the `#[slot(...)]` attribute value from a field, if present.
+/// Accepts either `#[slot(N)]` (numeric) or `#[slot(raw = EXPR)]`.
 /// Returns `None` when the field has no `#[slot]` attribute.
-pub(super) fn extract_optional_slot_attr(field: &syn::Field) -> syn::Result<Option<u64>> {
+pub(super) fn extract_optional_slot_attr(field: &syn::Field) -> syn::Result<Option<SlotAttr>> {
     let mut found: Option<&syn::Attribute> = None;
     for attr in &field.attrs {
         if attr.path().is_ident("slot") {
@@ -199,6 +211,21 @@ pub(super) fn extract_optional_slot_attr(field: &syn::Field) -> syn::Result<Opti
     let Some(attr) = found else {
         return Ok(None);
     };
-    let slot: syn::LitInt = attr.parse_args()?;
-    Ok(Some(slot.base10_parse::<u64>()?))
+    let parsed = attr.parse_args_with(|input: syn::parse::ParseStream| {
+        if input.peek(syn::Ident) {
+            let ident: syn::Ident = input.parse()?;
+            if ident != "raw" {
+                return Err(syn::Error::new_spanned(
+                    &ident,
+                    "expected an integer slot literal or `raw = <[u8; 32] expr>`",
+                ));
+            }
+            input.parse::<syn::Token![=]>()?;
+            Ok(SlotAttr::Raw(input.parse::<syn::Expr>()?))
+        } else {
+            let slot: syn::LitInt = input.parse()?;
+            Ok(SlotAttr::Numeric(slot.base10_parse::<u64>()?))
+        }
+    })?;
+    Ok(Some(parsed))
 }
diff --git a/crates/pvm-contract-macros/tests/native_proxy_slot.rs b/crates/pvm-contract-macros/tests/native_proxy_slot.rs
@@ -0,0 +1,99 @@
+#![cfg(not(feature = "abi-gen"))]
+//! Worked example: a minimal EIP-1967 upgradeable proxy.
+//!
+//! The implementation address lives at the standard pseudo-random slot
+//! `keccak256("eip1967.proxy.implementation") - 1`, deliberately outside the
+//! compiler-assigned sequential slot range so it never collides with regular
+//! fields. It's bound to a typed `Lazy<Address>` field via `#[slot(raw = …)]`,
+//! so reads/writes go through the borrow-checker's view-vs-mutating gate just
+//! like any other storage field — no raw `host.get_storage`, no unsafe.
+//!
+//! The EIP-1967 constant lives here in the contract, not the SDK: the SDK only
+//! provides the generic `#[slot(raw = KEY)]` mechanism.
+
+use pvm_contract_sdk::{
+    Address, Host, Lazy, MockHost, MockHostBuilder, StorageComponent, StorageKey,
+};
+
+/// `bytes32(uint256(keccak256("eip1967.proxy.implementation")) - 1)`.
+const IMPLEMENTATION_SLOT: [u8; 32] = [
+    0x36, 0x08, 0x94, 0xa1, 0x3b, 0xa1, 0xa3, 0x21, 0x06, 0x67, 0xc8, 0x28, 0x49, 0x2d, 0xb9, 0x8d,
+    0xca, 0x3e, 0x20, 0x76, 0xcc, 0x37, 0x35, 0xa9, 0x20, 0xa3, 0xca, 0x50, 0x5d, 0x38, 0x2b, 0xbc,
+];
+
+#[allow(dead_code)]
+#[pvm_contract_sdk::contract]
+mod upgradeable_proxy {
+    use super::*;
+
+    pub struct UpgradeableProxy {
+        #[slot(raw = IMPLEMENTATION_SLOT)]
+        pub impl_addr: Lazy<Address>,
+    }
+
+    impl UpgradeableProxy {
+        #[pvm_contract_sdk::constructor]
+        pub fn new(&mut self) {}
+
+        /// Current implementation address, read from the EIP-1967 slot.
+        #[pvm_contract_sdk::method]
+        pub fn implementation(&self) -> Address {
+            self.impl_addr.get()
+        }
+
+        /// Point the proxy at a new implementation contract.
+        #[pvm_contract_sdk::method]
+        pub fn upgrade_to(&mut self, new_implementation: Address) {
+            self.impl_addr.set(&new_implementation);
+        }
+    }
+}
+
+use upgradeable_proxy::UpgradeableProxy;
+
+/// Build an instance the same way the macro's on-chain path would: bind the
+/// `Lazy<Address>` field to the raw EIP-1967 slot, right-aligned like solc.
+fn proxy() -> (UpgradeableProxy, MockHost) {
+    let mock = MockHostBuilder::new().build();
+    let host = Host::from_dyn(::std::rc::Rc::new(mock.clone()));
+    let contract = UpgradeableProxy {
+        impl_addr: <Lazy<Address> as StorageComponent>::new_at(
+            StorageKey::from_raw(IMPLEMENTATION_SLOT),
+            (32 - <Lazy<Address> as StorageComponent>::PACKED_BYTES) as u8,
+            true,
+            host.clone(),
+        ),
+        host,
+    };
+    (contract, mock)
+}
+
+#[test]
+fn implementation_defaults_to_zero() {
+    let (p, _) = proxy();
+    assert_eq!(p.implementation(), Address::from([0u8; 20]));
+}
+
+#[test]
+fn upgrade_to_then_implementation_roundtrips() {
+    let (mut p, _) = proxy();
+    let impl_addr = Address::from([0x42; 20]);
+    p.upgrade_to(impl_addr);
+    assert_eq!(p.implementation(), impl_addr);
+}
+
+#[test]
+fn upgrade_to_writes_the_eip1967_slot_right_aligned() {
+    let (mut p, mock) = proxy();
+    let impl_addr = Address::from([0xCD; 20]);
+    p.upgrade_to(impl_addr);
+
+    // Confirm the write landed at the EIP-1967 slot, right-aligned like solc
+    // (low 20 bytes), so a slot written by a real Solidity proxy would decode.
+    let raw = mock
+        .get_raw_storage(&IMPLEMENTATION_SLOT)
+        .expect("implementation slot was written");
+    let mut expected = [0u8; 32];
+    expected[12..].copy_from_slice(impl_addr.as_ref() as &[u8; 20]);
+    assert_eq!(raw.as_slice(), &expected);
+}
