https://noir-lang.org/docs/assets/js/45bc75e3.5eef0c4d.js

1"use strict";(globalThis.webpackChunkdocs=globalThis.webpackChunkdocs||[]).push([[259],{20860(e,s,n){n.r(s),n.d(s,{assets:()=>d,contentTitle:()=>o,default:()=>h,frontMatter:()=>l,metadata:()=>r,toc:()=>a});const r=JSON.parse('{"id":"language/data_types/fields","title":"Fields","description":"Dive deep into the Field data type in Noir. Understand its methods, practical examples, and best practices to effectively use Fields in your Noir programs.","source":"@site/versioned_docs/version-v1.0.0-rc.1/language/data_types/fields.md","sourceDirName":"language/data_types","slug":"/language/data_types/fields","permalink":"/docs/v1.0.0-rc.1/language/data_types/fields","draft":false,"unlisted":false,"editUrl":"https://github.com/noir-lang/noir/edit/master/docs/versioned_docs/version-v1.0.0-rc.1/language/data_types/fields.md","tags":[],"version":"v1.0.0-rc.1","frontMatter":{"title":"Fields","description":"Dive deep into the Field data type in Noir. Understand its methods, practical examples, and best practices to effectively use Fields in your Noir programs.","keywords":["noir","field type","methods","examples","best practices"]},"sidebar":"sidebar","previous":{"title":"Data Types","permalink":"/docs/v1.0.0-rc.1/language/data_types/"},"next":{"title":"Integers","permalink":"/docs/v1.0.0-rc.1/language/data_types/integers"}}');var t=n(74848),i=n(28453);const l={title:"Fields",description:"Dive deep into the Field data type in Noir. Understand its methods, practical examples, and best practices to effectively use Fields in your Noir programs.",keywords:["noir","field type","methods","examples","best practices"]},o=void 0,d={},a=[{value:"Security Considerations for Field Arithmetic",id:"security-considerations-for-field-arithmetic",level:2},{value:"Methods",id:"methods",level:2},{value:"to_le_bits",id:"to_le_bits",level:3},{value:"to_be_bits",id:"to_be_bits",level:3},{value:"to_le_bytes",id:"to_le_bytes",level:3},{value:"to_be_bytes",id:"to_be_bytes",level:3},{value:"from_le_bytes",id:"from_le_bytes",level:3},{value:"from_be_bytes",id:"from_be_bytes",level:3},{value:"from_le_bytes_checked",id:"from_le_bytes_checked",level:3},{value:"from_be_bytes_checked",id:"from_be_bytes_checked",level:3},{value:"pow_32",id:"pow_32",level:3},{value:"assert_max_bit_size",id:"assert_max_bit_size",level:3},{value:"sgn0",id:"sgn0",level:3},{value:"lt",id:"lt",level:3}];function c(e){const s={a:"a",blockquote:"blockquote",code:"code",h2:"h2",h3:"h3",p:"p",pre:"pre",sub:"sub",sup:"sup",...(0,i.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(s.p,{children:"The field type corresponds to the native field type of the proving backend."}),"\n",(0,t.jsx)(s.p,{children:"The size of a Noir field depends on the elliptic curve's finite field for the proving backend  adopted. For example, a field would be a 254-bit integer when paired with the default backend that spans the Grumpkin curve."}),"\n",(0,t.jsx)(s.p,{children:"Fields support integer arithmetic:"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",children:"fn main(x : Field, y : Field)  {\n    let z = x + y;\n}\n"})}),"\n",(0,t.jsxs)(s.p,{children:[(0,t.jsx)(s.code,{children:"x"}),", ",(0,t.jsx)(s.code,{children:"y"})," and ",(0,t.jsx)(s.code,{children:"z"})," are all private fields in this example. Using the ",(0,t.jsx)(s.code,{children:"let"})," keyword we defined a new private value ",(0,t.jsx)(s.code,{children:"z"})," constrained to be equal to ",(0,t.jsx)(s.code,{children:"x + y"}),"."]}),"\n",(0,t.jsxs)(s.p,{children:["If proving efficiency is of priority, fields should be used as a default for solving problems. Smaller integer types (e.g. ",(0,t.jsx)(s.code,{children:"u64"}),") incur extra range constraints."]}),"\n",(0,t.jsx)(s.h2,{id:"security-considerations-for-field-arithmetic",children:"Security Considerations for Field Arithmetic"}),"\n",(0,t.jsxs)(s.p,{children:["Field arithmetic wraps around the field modulus without any overflow checks. This means operations like addition and multiplication can silently produce unexpected results if the values exceed the field modulus. For example, adding ",(0,t.jsx)(s.code,{children:"1"})," to the maximum field value wraps back to ",(0,t.jsx)(s.code,{children:"0"})," with no error."]}),"\n",(0,t.jsx)(s.p,{children:"Many use cases require standard integer arithmetic (e.g., enforcing that balance does not go negative). In these programs using explicitly sized integer types is necessary to catch overflows when proving a Noir program."}),"\n",(0,t.jsx)(s.h2,{id:"methods",children:"Methods"}),"\n",(0,t.jsx)(s.p,{children:"After declaring a Field, you can use these common methods on it:"}),"\n",(0,t.jsx)(s.h3,{id:"to_le_bits",children:"to_le_bits"}),"\n",(0,t.jsx)(s.p,{children:"Transforms the field into an array of bits, Little Endian."}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",metastring:'title="to_le_bits" showLineNumbers ',children:"pub fn to_le_bits<let N: u32>(self: Self) -> [bool; N] {\n"})}),"\n",(0,t.jsxs)(s.blockquote,{children:["\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.sup,{children:(0,t.jsx)(s.sub,{children:(0,t.jsx)(s.a,{href:"https://github.com/noir-lang/noir/blob/master/noir_stdlib/src/field/mod.nr#L29-L31",target:"_blank",rel:"noopener noreferrer",children:"Source code: noir_stdlib/src/field/mod.nr#L29-L31"})})})}),"\n"]}),"\n",(0,t.jsx)(s.p,{children:"example:"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",metastring:'title="to_le_bits_example" showLineNumbers ',children:"fn test_to_le_bits() {\n    let field = 2;\n    let bits: [bool; 8] = field.to_le_bits();\n    assert_eq(bits, [false, true, false, false, false, false, false, false]);\n}\n"})}),"\n",(0,t.jsxs)(s.blockquote,{children:["\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.sup,{children:(0,t.jsx)(s.sub,{children:(0,t.jsx)(s.a,{href:"https://github.com/noir-lang/noir/blob/master/noir_stdlib/src/field/mod.nr#L403-L409",target:"_blank",rel:"noopener noreferrer",children:"Source code: noir_stdlib/src/field/mod.nr#L403-L409"})})})}),"\n"]}),"\n",(0,t.jsx)(s.h3,{id:"to_be_bits",children:"to_be_bits"}),"\n",(0,t.jsx)(s.p,{children:"Transforms the field into an array of bits, Big Endian."}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",metastring:'title="to_be_bits" showLineNumbers ',children:"pub fn to_be_bits<let N: u32>(self: Self) -> [bool; N] {\n"})}),"\n",(0,t.jsxs)(s.blockquote,{children:["\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.sup,{children:(0,t.jsx)(s.sub,{children:(0,t.jsx)(s.a,{href:"https://github.com/noir-lang/noir/blob/master/noir_stdlib/src/field/mod.nr#L61-L63",target:"_blank",rel:"noopener noreferrer",children:"Source code: noir_stdlib/src/field/mod.nr#L61-L63"})})})}),"\n"]}),"\n",(0,t.jsx)(s.p,{children:"example:"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",metastring:'title="to_be_bits_example" showLineNumbers ',children:"fn test_to_be_bits() {\n    let field = 2;\n    let bits: [bool; 8] = field.to_be_bits();\n    assert_eq(bits, [false, false, false, false, false, false, true, false]);\n}\n"})}),"\n",(0,t.jsxs)(s.blockquote,{children:["\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.sup,{children:(0,t.jsx)(s.sub,{children:(0,t.jsx)(s.a,{href:"https://github.com/noir-lang/noir/blob/master/noir_stdlib/src/field/mod.nr#L394-L400",target:"_blank",rel:"noopener noreferrer",children:"Source code: noir_stdlib/src/field/mod.nr#L394-L400"})})})}),"\n"]}),"\n",(0,t.jsx)(s.h3,{id:"to_le_bytes",children:"to_le_bytes"}),"\n",(0,t.jsx)(s.p,{children:"Transforms into an array of bytes, Little Endian"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",metastring:'title="to_le_bytes" showLineNumbers ',children:"pub fn to_le_bytes<let N: u32>(self: Self) -> [u8; N] {\n"})}),"\n",(0,t.jsxs)(s.blockquote,{children:["\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.sup,{children:(0,t.jsx)(s.sub,{children:(0,t.jsx)(s.a,{href:"https://github.com/noir-lang/noir/blob/master/noir_stdlib/src/field/mod.nr#L93-L95",target:"_blank",rel:"noopener noreferrer",children:"Source code: noir_stdlib/src/field/mod.nr#L93-L95"})})})}),"\n"]}),"\n",(0,t.jsx)(s.p,{children:"example:"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",metastring:'title="to_le_bytes_example" showLineNumbers ',children:"fn test_to_le_bytes() {\n    let field = 2;\n    let bytes: [u8; 8] = field.to_le_bytes();\n    assert_eq(bytes, [2, 0, 0, 0, 0, 0, 0, 0]);\n    assert_eq(Field::from_le_bytes::<8>(bytes), field);\n}\n"})}),"\n",(0,t.jsxs)(s.blockquote,{children:["\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.sup,{children:(0,t.jsx)(s.sub,{children:(0,t.jsx)(s.a,{href:"https://github.com/noir-lang/noir/blob/master/noir_stdlib/src/field/mod.nr#L422-L429",target:"_blank",rel:"noopener noreferrer",children:"Source code: noir_stdlib/src/field/mod.nr#L422-L429"})})})}),"\n"]}),"\n",(0,t.jsx)(s.h3,{id:"to_be_bytes",children:"to_be_bytes"}),"\n",(0,t.jsx)(s.p,{children:"Transforms into an array of bytes, Big Endian"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",metastring:'title="to_be_bytes" showLineNumbers ',children:"pub fn to_be_bytes<let N: u32>(self: Self) -> [u8; N] {\n"})}),"\n",(0,t.jsxs)(s.blockquote,{children:["\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.sup,{children:(0,t.jsx)(s.sub,{children:(0,t.jsx)(s.a,{href:"https://github.com/noir-lang/noir/blob/master/noir_stdlib/src/field/mod.nr#L130-L132",target:"_blank",rel:"noopener noreferrer",children:"Source code: noir_stdlib/src/field/mod.nr#L130-L132"})})})}),"\n"]}),"\n",(0,t.jsx)(s.p,{children:"example:"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",metastring:'title="to_be_bytes_example" showLineNumbers ',children:"fn test_to_be_bytes() {\n    let field = 2;\n    let bytes: [u8; 8] = field.to_be_bytes();\n    assert_eq(bytes, [0, 0, 0, 0, 0, 0, 0, 2]);\n    assert_eq(Field::from_be_bytes::<8>(bytes), field);\n}\n"})}),"\n",(0,t.jsxs)(s.blockquote,{children:["\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.sup,{children:(0,t.jsx)(s.sub,{children:(0,t.jsx)(s.a,{href:"https://github.com/noir-lang/noir/blob/master/noir_stdlib/src/field/mod.nr#L412-L419",target:"_blank",rel:"noopener noreferrer",children:"Source code: noir_stdlib/src/field/mod.nr#L412-L419"})})})}),"\n"]}),"\n",(0,t.jsx)(s.h3,{id:"from_le_bytes",children:"from_le_bytes"}),"\n",(0,t.jsxs)(s.p,{children:["Parses a Little Endian byte array into a field element. If the byte array represents a value\

1ngreater than or equal to the field modulus then the result will silently wrap around. Use\n",(0,t.jsx)(s.a,{href:"#from_le_bytes_checked",children:(0,t.jsx)(s.code,{children:"from_le_bytes_checked"})})," when canonical inputs are required."]}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",metastring:'title="from_le_bytes" showLineNumbers ',children:"pub fn from_le_bytes<let N: u32>(bytes: [u8; N]) -> Field {\n"})}),"\n",(0,t.jsxs)(s.blockquote,{children:["\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.sup,{children:(0,t.jsx)(s.sub,{children:(0,t.jsx)(s.a,{href:"https://github.com/noir-lang/noir/blob/master/noir_stdlib/src/field/mod.nr#L210-L212",target:"_blank",rel:"noopener noreferrer",children:"Source code: noir_stdlib/src/field/mod.nr#L210-L212"})})})}),"\n"]}),"\n",(0,t.jsx)(s.h3,{id:"from_be_bytes",children:"from_be_bytes"}),"\n",(0,t.jsxs)(s.p,{children:["Parses a Big Endian byte array into a field element. If the byte array represents a value\ngreater than or equal to the field modulus then the result will silently wrap around. Use\n",(0,t.jsx)(s.a,{href:"#from_be_bytes_checked",children:(0,t.jsx)(s.code,{children:"from_be_bytes_checked"})})," when canonical inputs are required."]}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",metastring:'title="from_be_bytes" showLineNumbers ',children:"pub fn from_be_bytes<let N: u32>(bytes: [u8; N]) -> Field {\n"})}),"\n",(0,t.jsxs)(s.blockquote,{children:["\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.sup,{children:(0,t.jsx)(s.sub,{children:(0,t.jsx)(s.a,{href:"https://github.com/noir-lang/noir/blob/master/noir_stdlib/src/field/mod.nr#L232-L234",target:"_blank",rel:"noopener noreferrer",children:"Source code: noir_stdlib/src/field/mod.nr#L232-L234"})})})}),"\n"]}),"\n",(0,t.jsx)(s.h3,{id:"from_le_bytes_checked",children:"from_le_bytes_checked"}),"\n",(0,t.jsxs)(s.p,{children:["Like ",(0,t.jsx)(s.a,{href:"#from_le_bytes",children:(0,t.jsx)(s.code,{children:"from_le_bytes"})})," but asserts that the input is a canonical representation,\ni.e. that the value encoded by ",(0,t.jsx)(s.code,{children:"bytes"})," is strictly less than the field modulus. Triggers a\nconstraint failure otherwise."]}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",metastring:'title="from_le_bytes_checked" showLineNumbers ',children:"pub fn from_le_bytes_checked<let N: u32>(bytes: [u8; N]) -> Field {\n"})}),"\n",(0,t.jsxs)(s.blockquote,{children:["\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.sup,{children:(0,t.jsx)(s.sub,{children:(0,t.jsx)(s.a,{href:"https://github.com/noir-lang/noir/blob/master/noir_stdlib/src/field/mod.nr#L255-L257",target:"_blank",rel:"noopener noreferrer",children:"Source code: noir_stdlib/src/field/mod.nr#L255-L257"})})})}),"\n"]}),"\n",(0,t.jsx)(s.h3,{id:"from_be_bytes_checked",children:"from_be_bytes_checked"}),"\n",(0,t.jsxs)(s.p,{children:["Like ",(0,t.jsx)(s.a,{href:"#from_be_bytes",children:(0,t.jsx)(s.code,{children:"from_be_bytes"})})," but asserts that the input is a canonical representation,\ni.e. that the value encoded by ",(0,t.jsx)(s.code,{children:"bytes"})," is strictly less than the field modulus. Triggers a\nconstraint failure otherwise."]}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",metastring:'title="from_be_bytes_checked" showLineNumbers ',children:"pub fn from_be_bytes_checked<let N: u32>(bytes: [u8; N]) -> Field {\n"})}),"\n",(0,t.jsxs)(s.blockquote,{children:["\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.sup,{children:(0,t.jsx)(s.sub,{children:(0,t.jsx)(s.a,{href:"https://github.com/noir-lang/noir/blob/master/noir_stdlib/src/field/mod.nr#L281-L283",target:"_blank",rel:"noopener noreferrer",children:"Source code: noir_stdlib/src/field/mod.nr#L281-L283"})})})}),"\n"]}),"\n",(0,t.jsx)(s.h3,{id:"pow_32",children:"pow_32"}),"\n",(0,t.jsx)(s.p,{children:"Returns the value to the power of the specified exponent"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",children:"fn pow_32(self, exponent: Field) -> Field\n"})}),"\n",(0,t.jsx)(s.p,{children:"example:"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",children:"fn main() {\n    let field = 2\n    let pow = field.pow_32(4);\n    assert(pow == 16);\n}\n"})}),"\n",(0,t.jsx)(s.h3,{id:"assert_max_bit_size",children:"assert_max_bit_size"}),"\n",(0,t.jsxs)(s.p,{children:["Adds a constraint to specify that the field can be represented with ",(0,t.jsx)(s.code,{children:"bit_size"})," number of bits"]}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",metastring:'title="assert_max_bit_size" showLineNumbers ',children:"pub fn assert_max_bit_size<let BIT_SIZE: u32>(self) {\n"})}),"\n",(0,t.jsxs)(s.blockquote,{children:["\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.sup,{children:(0,t.jsx)(s.sub,{children:(0,t.jsx)(s.a,{href:"https://github.com/noir-lang/noir/blob/master/noir_stdlib/src/field/mod.nr#L10-L12",target:"_blank",rel:"noopener noreferrer",children:"Source code: noir_stdlib/src/field/mod.nr#L10-L12"})})})}),"\n"]}),"\n",(0,t.jsx)(s.p,{children:"example:"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",children:"fn main() {\n    let field = 2\n    field.assert_max_bit_size::<32>();\n}\n"})}),"\n",(0,t.jsx)(s.h3,{id:"sgn0",children:"sgn0"}),"\n",(0,t.jsx)(s.p,{children:"Parity of (prime) Field element, i.e. sgn0(x mod p) = false if x \u2208 {0, ..., p-1} is even, otherwise sgn0(x mod p) = true."}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",children:"fn sgn0(self) -> bool\n"})}),"\n",(0,t.jsx)(s.h3,{id:"lt",children:"lt"}),"\n",(0,t.jsx)(s.p,{children:"Returns true if the field is less than the other field"}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-rust",children:"pub fn lt(self, another: Field) -> bool\n"})})]})}function h(e={}){const{wrapper:s}={...(0,i.R)(),...e.components};return s?(0,t.jsx)(s,{...e,children:(0,t.jsx)(c,{...e})}):c(e)}},28453(e,s,n){n.d(s,{R:()=>l,x:()=>o});var r=n(96540);const t={},i=r.createContext(t);function l(e){const s=r.useContext(i);return r.useMemo(function(){return"function"==typeof e?e(s):{...s,...e}},[s,e])}function o(e){let s;return s=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:l(e.components),r.createElement(i.Provider,{value:s},e.children)}}}]);