Type Safety

TYPE_SAFETY Skill

Trigger Pattern: Always (Sui Move) -- generic type exploitation Inject Into: Breadth agents, depth-state-trace

For every generic function and parameterized type in the protocol:

STEP PRIORITY: Steps 4 (OTW Analysis) and 6 (Coin/Balance Type Safety) are where HIGH/CRITICAL severity findings most commonly hide. Do NOT rush these steps. If constrained, skip conditional sections before skipping 4 or 6.

1. Generic Function Inventory

Enumerate ALL functions with type parameters across all modules:

Sui type parameter semantics:

• <T> -- unconstrained. T can be ANY type. Maximally permissive.
• <T: key + store> -- T must be an object that can be freely transferred.
• <T: drop> -- T can be discarded. Often used for witness patterns.
• <phantom T> -- T is not used at runtime, only for type distinction (e.g., Coin<phantom T>). No ability constraints enforced on phantom params at the struct level.

2. Type Parameter Constraint Analysis

For each generic function, verify constraints are sufficient:

2a. Under-Constrained Parameters

Check: For each type parameter, trace how it is actually used in the function body:

• If stored in a struct field -> needs at minimum store
• If used as an object -> needs key
• If discarded without explicit destruction -> needs drop
• If the function works correctly with ANY type -> unconstrained is correct

2b. Over-Constrained Parameters (Info-Level)

Note: Over-constraining is not a security issue but limits composability. Document as Informational.

2c. Phantom Type Correctness

Rule: Phantom type parameters MUST NOT be used in runtime field types (non-phantom positions). If a phantom param is used in a non-phantom position, the compiler rejects it. But check: is the phantom param providing meaningful type distinction, or can an attacker substitute any type?

2d. Mutable Reference Assignment Correctness

For every function that destructures a mutable reference or binds &mut field references, verify assignments update values rather than rebinding references:

Checks:

• If destructuring &mut Struct, treat destructured fields as references, not copied values.
• Assignment like left = limit rebinds the local reference; it does not copy limit into the left field. Confirm the intended code uses *left = *limit or equivalent.
• After any reference rebinding, trace subsequent *ref = ... writes. Do they now write to the original field or to another field?
• Prioritize reset/quota/epoch/cooldown/accounting logic, where a wrong-field write can permanently corrupt limits or lock users out.

3. Type Witness Pattern Audit

Identify all witness patterns (structs used for one-time authorization):

Witness security checks:

• Is the witness created ONLY in the intended function? (Check all new / constructor paths.)
• Is the witness consumed (dropped or destructured) immediately after use?
• Can the witness be stored? (If it has store -> it can persist beyond its intended scope -> FINDING.)
• Can the witness be copied? (If it has copy -> it can be reused -> FINDING.)
• Is the witness type public? (If the struct is public, external modules can potentially construct it if they can satisfy its fields.)

3a. Witness Forgery Check

For each witness type:

Can an attacker construct this witness type?
1. Is the struct definition public (`public struct`)? -> External modules CAN create instances if fields are accessible
2. Does the struct have fields? -> If no fields (unit struct), only the defining module can create it
3. Are all field types accessible to external modules? -> If yes, external construction possible
4. Is construction gated by `init` or capability? -> Check the gate

Rule: A witness with a public struct definition and publicly-accessible field types is forgeable from external modules. This is a CRITICAL finding if the witness gates value creation (coin minting, capability issuance, etc.).

4. One-Time Witness (OTW) Analysis

Identify all OTW patterns:

Sui OTW rules:

• OTW type name MUST match the module name in UPPERCASE.
• OTW MUST have drop ability (and typically no other abilities).
• OTW is automatically created by the Sui runtime and passed to init on module publish.
• OTW MUST be consumed in init (typically passed to coin::create_currency or similar).

Security checks:

• Does the OTW have ONLY drop ability? If it has copy -> can be duplicated (should be impossible due to Sui's OTW rules, but verify). If it has store -> can be persisted past init -> FINDING.
• Is the OTW consumed (used as a move value, not just referenced) in init? If stored instead of consumed -> it can be reused.
• Package upgrade: Sui package upgrades do NOT re-run init. Is the protocol relying on init for setup that should be repeatable? If the module uses OTW to create a TreasuryCap or Publisher, those are one-time-only.
• Can the OTW check be bypassed? Functions that accept T: drop as a witness without verifying it is the actual OTW type -> can be called with any drop-able type.

4a. OTW Verification Pattern

Check if the protocol uses sui::types::is_one_time_witness<T>() to verify OTW:

Rule: Any public function that accepts a generic witness <T: drop> without calling is_one_time_witness can be called with any droppable type, not just the actual OTW. This is a HIGH finding if the function creates currencies, capabilities, or other privileged objects.

5. Generic Type Confusion Attacks

Model attacks where an attacker substitutes an unexpected type:

5a. Function-Level Type Confusion

For each public generic function:

Can an attacker call function<MaliciousType>() where the protocol expects function<ExpectedType>()?
1. What type does the protocol intend?
2. What constraints prevent substitution?
3. What happens if a different type is passed?

5b. Struct-Level Type Confusion

For each generic struct:

Pool<T> { balance: Balance<T>, ... }

Can an attacker create Pool<FakeToken> and interact with Pool<RealToken>'s functions?

Check: Does the protocol use type parameters to distinguish pools/vaults? If yes:

• Are operations on Pool<A> and Pool<B> fully isolated?
• Can an attacker drain Pool<A> by exploiting Pool<FakeA>?
• Is there a registry/mapping that validates the type parameter? (e.g., Table<TypeName, PoolConfig>)

5c. Generic Type to Config/Object Binding

Move generics prove that Pool<BTC> holds BTC, but they do NOT prove that a runtime selector, config row, position, or receipt supplied in the same call belongs to that generic type. For every public/package function accepting both generic type parameters and runtime identity inputs, build this table:

Checks:

• If a function accepts T plus an asset index/config ID, does it validate type_name::get<T>() against the stored config row?
• If an index can be derived from T, does the function derive it instead of trusting a user-supplied index?
• If a position/receipt/order was created with a specific pool, does the later function assert object::id(pool) == stored_pool_id or equivalent?
• If there are multiple dependent type parameters (X, Y, SX, LP), does the function bind all of them to the stored position/config, not just the coin type?
• If no binding exists, model attacker flow with a valid object of the wrong semantic pool/config and mark as finding if value, collateral, debt, or accounting can move under the wrong identity.

6. Coin/Balance Type Safety

Specific analysis for Coin<T> and Balance<T> patterns:

6a. Coin Type Verification

Sui Coin safety model:

• Coin<T> is parameterized by the coin type T.
• Creating Coin<T> requires a TreasuryCap<T>, which is created via OTW in init.
• An attacker CANNOT create Coin<SUI> because they don't have TreasuryCap<SUI>.
• But an attacker CAN create Coin<ATTACKER_TOKEN> and pass it to a function expecting Coin<T> if T is generic.

Checks:

• Do functions that handle coins use specific types (Coin<SUI>) or generic (Coin<T>)?
• If generic: is T validated against an allowed set?
• Can Balance<FakeToken> be joined with Balance<RealToken>? (NO -- type system prevents this. But verify no unsafe transmutation exists.)
• Are Coin split/merge operations type-safe? (coin::split preserves T.)

6b. Balance Accounting Type Safety

Check: At every point where Balance<T> is converted to/from Coin<T>, is the type parameter T consistent? The compiler enforces this for concrete types, but for generic functions operating on Balance<T>, trace that T remains the same throughout the flow.

7. Publisher and Package Authority

Analyze Publisher object usage:

Security checks:

• Publisher proves package authorship. Functions that accept &Publisher trust the caller is the package publisher.
• Is Publisher stored in a shared object (accessible to anyone with the right reference)?
• Can Publisher be transferred to a malicious actor?
• Are there functions that accept Publisher from external callers? (These trust the caller is a publisher.)
• Package upgrade: After an upgrade, the original Publisher remains valid. Does the protocol account for this?

Finding Template

**ID**: [TS-N]
**Severity**: [CRITICAL if coin forgery/capability bypass, HIGH if type confusion with value, MEDIUM if witness issue]
**Step Execution**: check1,2,3,4,5,6,7 | X(reasons) | ?(uncertain)
**Rules Applied**: [R4:Y, R5:Y, R10:Y, ...]
**Depth Evidence**: [VARIATION:T=FakeToken vs T=SUI], [TRACE:generic_fn<Attacker>->state_corruption]
**Location**: module::function
**Title**: [Type safety issue] in [function] enables [attack/bypass]
**Description**: [Specific type parameter exploitation path with concrete substitute type]
**Impact**: [Unauthorized coin minting, capability forgery, pool drainage, accounting corruption]

Step Execution Checklist (MANDATORY)

CRITICAL: You MUST report completion status for ALL sections. Findings with incomplete sections will be flagged for depth review.

Cross-Reference Markers

After Section 3 (Witness Pattern Audit):

• Cross-reference with ABILITY_ANALYSIS Section 4 (Capability Pattern Audit) -- witnesses often gate capabilities
• IF witness is forgeable -> escalate to CRITICAL and cross-reference all functions that accept it

After Section 4 (OTW Analysis):

• Cross-reference with ABILITY_ANALYSIS Section 8 (Module Initializer Audit) -- OTW is consumed in init
• IF OTW not consumed -> check if TreasuryCap or Publisher can be created multiple times

After Section 6 (Coin/Balance Type Safety):

• Cross-reference with TOKEN_FLOW_TRACING for multi-token accounting
• IF generic coin functions lack type verification -> model type confusion attack with concrete substitute

After Section 7 (Publisher Authority):

• IF Publisher stored in shared object -> cross-reference with SEMI_TRUSTED_ROLES (who can access it?)
• IF package upgrade possible -> document Publisher persistence across upgrades