Improving Visibility Semantics in Compact

[0xisk]

I want to clarify my position on the compiler exporting ledger state and circuit visibility.

I agree with Andrew’s concern about automatically exporting. However, the current system is still not ergonomic: when building a top-level Compact contract, you must manually re-export every export ledger STATE (sometimes also re-export circuits) from all imported modules. In a large project this becomes error-prone, and the only negative effect is on the generated TypeScript representation of the top-level contract — not on the actual contract logic.

Three Visibility Cases (Ledger + Circuits)

Compact today conceptually mirrors Solidity, but the semantics end up being blurred because export is overloaded. Here are the three real visibility cases:

---

1. Private Visibility (Solidity → private)

These members live only inside the module that defines them. They cannot be imported by other modules, and the compiler does not include them in TS artifacts.

module M {
    ledger privateMState: boolean;
    circuit privateMCircuit: [] { ... }
}

// top-level
import M; // cannot import privateMState or privateMCircuit

ledger privateTopState: boolean;
circuit privateTopCircuit: [] { ... }

---

2. Internal / Public Visibility (Solidity → internal, public)

These members can be imported into other modules. But here’s the confusing part:
Even if module M declares them with export, the compiler does not emit them into the final TS representation unless the top-level module re-exports them manually.

Example

// EXAMPLE 3 – inside module M
module M {
    ledger privateMState: boolean;

    export internalMState: boolean;

    circuit privateMCircuit: [] { ... }

    export internalMCircuit: [] { ... }
}

Now in the top-level:

// EXAMPLE 4 – top level
import M prefix M_; // can import internalCircuit()

ledger privateTopState;
export ledger publicTopState;

circuit privateTopCircuit: [] { ... }

export circuit useMInternalMState: boolean {
    return M_internalMState;
}

export circuit useMInternalCircuits: [] {
    return M_internalMCircuits();
}

Compiler behavior:
Only exported items from the top-level are represented in TS.
So even though M exported two items, they are invisible unless re-exported manually:

// EXAMPLE 5 – explicit re-export
import M prefix M_;
export { M_internalMCircuit, M_internalMState };

This mixing of visibility ("internal" vs "public") with explicit re-exporting is what makes things verbose and confusing in large project structures.

---

Suggestion: Replace export With Explicit Visibility Keywords

Instead of overloading export, we could adopt explicit visibility modifiers similar to Solidity:

• private
• internal
• public

Rewriting the examples using these keywords:

// EXAMPLE 6 – inside module M
module M {
    private  ledger privateMState: boolean;
    internal ledger internalMState: boolean;
    public  ledger publicMState: boolean;

    private  circuit privateMCircuit: [] { ... }
    internal circuit internalMCircuit: [] { ... }
    public  circuit publicMCircuit: [] { ... }
}

And the top-level contract:

// EXAMPLE 7 – top level
import M prefix M_;

private  ledger privateTopState: boolean;
internal ledger internalTopState: boolean;
public  ledger publicTopState: boolean;

private circuit privateTopCircuit: [] { ... }

// explicitly public circuits using internal module state
public circuit useMInternalMState: boolean {
    return M_internalMState;
}

public circuit useMInternalCircuits: [] {
    return M_internalMCircuits();
}

Expected Compiler Behavior

Now the compiler can automatically generate the correct TS representation for top-level contract on example 7 without requiring manual re-exports:

export type Ledger = {
    publicMState: boolean;
    publicTopState: boolean;
}

export type ImpureCircuits = {
    publicMCircuit: () => ...;
    useMInternalMState: () => ...;
    useMInternalCircuits: () => ...;
}

This provides:

• clearer, more accurate visibility semantics
• no more accidental omissions in TS generation
• no need for repetitive and fragile export { M_something } patterns

Overall, explicit visibility modifiers would significantly simplify large-scale Compact projects.

[andrew-fleming]

This is a much better proposal for exposing ledger vars assuming it's technically feasible. Opt-in > auto export. Another interesting thing to consider is should explicit visibility be enforced by the compiler to avoid surprises? Or should it default to private like it does now? I assume from this proposal you think it should be enforced

[0xisk]

I assume from this proposal you think it should be enforced

Yes I think that should be auto-exported by the Compiler, and in fact the proposal suggests constrained keywords that are clear and won't be miss-used, and will be at the end the developer responsibility to assign public, to whatever, and then the compiler will auto-export that. I think that is the same as in Solidity compiler and the exported ABI.