Document the #[oracle] attribute

[Savio-Sou]

Problem

The #[foreign_call] attribute has been surfaced in multiple discussions as a feature for fetching information outside of the Noir program, but we don't currently have written explanations of how it is used.

Happy Case

Document how is #[foreign_call] used in the Noir docs with examples.

Alternatives Considered

No response

Additional Context

Non-exhausive / potentially inaccurate list of reference PRs I came across:

• feat(noir_js): allow providing foreign call handlers in noirJS #3294
• feat: allow providing custom foreign call executors to execute_circuit #3506
• feat: allow passing custom foreign call handlers when creating proofs in NoirJS #3764
• feat: Resolve oracle calls via JSON-RPC #3902

Would you like to submit a PR for this Issue?

No

Support Needs

No response

[Savio-Sou]

@signorecello would you like to pair with @TomAFrench and @sirasistant to work on this?

[Savio-Sou]

Relatedly is #[oracle] the same as #[foreign_call]? (example)
If not we should create a separate issue to also document it.

[kevaundray]

#[foreign] is a compiler attribute for specifying blackbox functions whereas #[oracle] tells the compiler to delegate execution of a function to something outside of Noir

[Savio-Sou]

Does that mean Noir devs are intended to use #[oracle] but not necessarily #[foreign_call]?
(And is #[foreign_call] and #[foreign] the same?)

[kevaundray]

Noir devs should not use any of those I think in most cases -- oracles are for people who want to have their own runtimes like aztec, ie I can't depend on a library that has an oracle in it unless it is an oracle from the Noir runtime, like println

[Savio-Sou]

Right, perhaps an advanced rather than general use case but would for example #3767 be where Noir devs could find#[oracle] useful?

[TomAFrench]

#[foreign_call] doesn't exist. I got those mixed up in an example a while back.

[TomAFrench]

Noir devs should not use any of those I think in most cases -- oracles are for people who want to have their own runtimes like aztec, ie I can't depend on a library that has an oracle in it unless it is an oracle from the Noir runtime, like println

Generally agree although I can see an argument for allowing them in bin packages, i.e. as it lives in the package you running then you aren't pulling in this new oracle call unawares so you're more likely to run the package in an environment which supplies a handler for it.

[signorecello]

This is where diátaxis framework shines: we don't have to not document something, as it is delegated to reference material. It is still there, but not surfaced as something that works out-of-the-box.

To work, I'll be doing a how-to guide which will come with its own section on the runtime part.

This should be documented in reference, though. I'll try to find a nice place for it, and we can follow the same pattern for future situations like this.