@crediolabs/policy-synth 0.1.5 → 0.1.6

package/src/contracts/policy-template/OZ_POLICY_TRAIT.md

@@ -0,0 +1,171 @@
+# OZ_POLICY_TRAIT.md — OpenZeppelin Stellar Accounts Pinned Trait Definitions
+
+> **Pinned at:** `OpenZeppelin/stellar-contracts@v0.8.0-rc.3`  
+> **Commit SHA:** `4114bb8e2d7f090bdd9f45731e0607071d5ecea2`  
+> **Permalink:** https://github.com/OpenZeppelin/stellar-contracts/blob/4114bb8e2d7f090bdd9f45731e0607071d5ecea2/packages/accounts/src/policies/mod.rs  
+> **Policy trait file:** https://github.com/OpenZeppelin/stellar-contracts/blob/4114bb8e2d7f090bdd9f45731e0607071d5ecea2/packages/accounts/src/policies/mod.rs  
+> **Storage file (Signer, ContextRule, add_context_rule):** https://github.com/OpenZeppelin/stellar-contracts/blob/4114bb8e2d7f090bdd9f45731e0607071d5ecea2/packages/accounts/src/smart_account/storage.rs  
+> **Verified:** 2026-07-24 by W3 agent
+
+---
+
+## Policy Trait
+
+Source: `packages/accounts/src/policies/mod.rs` (permalinked above)
+
+```rust
+pub trait Policy {
+    type AccountParams: FromVal<Env, Val>;
+
+    fn enforce(
+        e: &Env,
+        context: Context,
+        authenticated_signers: Vec<Signer>,
+        context_rule: ContextRule,
+        smart_account: Address,
+    );
+
+    fn install(
+        e: &Env,
+        install_params: Self::AccountParams,
+        context_rule: ContextRule,
+        smart_account: Address,
+    );
+
+    fn uninstall(e: &Env, context_rule: ContextRule, smart_account: Address);
+}
+```
+
+### Key observations
+
+- `Policy::enforce` receives a **single `Context`** — the authorization context being enforced. It does **NOT** carry a `sub_invocations` field. Sub-invocations live under `InvokerContractAuthEntry::Contract(SubContractInvocation)` and are used for `authorize_as_current_contract`, not passed to `Policy::enforce`.
+- The `Context` type is defined in `soroban_sdk::auth::Context` (external, not in this repo).
+- `install` takes `Self::AccountParams` — the interpreter's `PolicyInstallParams` struct satisfies this via `FromVal` / `IntoVal`.
+- `uninstall` requires the `ContextRule` to be passed by the caller; the interpreter stores it to compute the `rule_id`.
+
+---
+
+## Signer Enum
+
+Source: `packages/accounts/src/smart_account/storage.rs` lines 148–155 (permalinked above)
+
+```rust
+pub enum Signer {
+    Delegated(Address),
+    External(Address, Bytes),
+}
+```
+
+**Two variants only.** No `Key` variant. No `SmartAccount` variant. The verifier address + key bytes for an external signer are carried in the `External` variant itself. There is **no master/non-master discriminator** on the type.
+
+---
+
+## ContextRuleType Enum
+
+Source: `packages/accounts/src/smart_account/storage.rs` lines 170–177
+
+```rust
+pub enum ContextRuleType {
+    Default,
+    CallContract(Address),
+    CreateContract(BytesN<32>),
+}
+```
+
+---
+
+## ContextRule Struct
+
+Source: `packages/accounts/src/smart_account/storage.rs` lines 179–199
+
+```rust
+pub struct ContextRule {
+    pub id: u32,
+    pub context_type: ContextRuleType,
+    pub name: String,
+    pub signers: Vec<Signer>,
+    pub signer_ids: Vec<u32>,
+    pub policies: Vec<Address>,
+    pub policy_ids: Vec<u32>,
+    pub valid_until: Option<u32>,
+}
+```
+
+---
+
+## add_context_rule Signature
+
+Source: `packages/accounts/src/smart_account/storage.rs` lines 620–645
+
+```rust
+pub fn add_context_rule(
+    e: &Env,
+    context_type: &ContextRuleType,
+    name: &String,
+    valid_until: Option<u32>,
+    signers: &Vec<Signer>,
+    policies: &Map<Address, Val>,
+) -> ContextRule
+```
+
+### Auth requirements
+
+- `add_context_rule` is called by the **smart account itself** (the contract owning the context rules).
+- Auth is enforced by Soroban's `require_auth` on the calling context — the smart account's master signer (or a delegated signer with sufficient weight) must authorize the call.
+- The interpreter's `install` function is called **within the same transaction** as `add_context_rule` and receives the same `smart_account` address.
+- **The interpreter does NOT need to read the smart account's master set** — the master signer authorizes `add_context_rule` directly; the interpreter receives the already-authorized `ContextRule` and `smart_account` address.
+
+### Safe mechanism for master-only install
+
+The committed safe mechanism is **two-step install** (not out-of-band master const):
+1. Owner calls `add_context_rule` with the interpreter address + initial rule.
+2. Interpreter's `install` is called within the same auth context — the `Context` passed to `Policy::enforce` confirms the call is authorized by the smart account's current signer set.
+3. Re-install is structurally possible via `install_nonce` (stored nonce + 1 check).
+
+---
+
+## Framework Limits (OZ Hard Limits)
+
+Source: `packages/accounts/src/smart_account/storage.rs` (permalinked above)
+
+| Limit | Value |
+|---|---|
+| `maxPoliciesPerRule` | **5** |
+| `maxSignersPerRule` | **15** |
+| Per-account rule cap | **None** (OZ imposes no cap) |
+
+These are enforced by OZ internally; the interpreter enforces the same caps at install time.
+
+---
+
+## add_policy (Second Attach Path)
+
+`add_context_rule` installs the rule + signers. A **second separate call** (`add_policy`) attaches a policy contract to an existing rule:
+
+```rust
+pub fn add_policy(
+    e: &Env,
+    context_rule_id: u32,
+    policy: Address,
+    install_param: Val,
+) -> u32
+```
+
+Parameters:
+- `context_rule_id: u32` — the rule to attach to
+- `policy: Address` — the policy contract address
+- `install_param: Val` — arbitrary `Val` passed to `Policy::install`; for the interpreter this is `PolicyInstallParams` as ScVal
+- Returns `u32` — the new policy id within the rule
+
+**Auth:** same pattern — `require_auth` on the smart account. The `policy` address must point to a deployed `Policy` contract.
+
+---
+
+## Related Files
+
+| File | Purpose |
+|---|---|
+| `packages/accounts/src/smart_account/mod.rs` | Smart account contract entry points |
+| `packages/accounts/src/smart_account/storage.rs` | Signer, ContextRule, add_context_rule, add_policy |
+| `packages/accounts/src/policies/mod.rs` | Policy trait definition |
+| `packages/accounts/src/policies/oz_primitive.rs` | Built-in OZ policies (spending_limit, threshold) |