> ## Documentation Index > Fetch the complete documentation index at: https://docs.near.org/llms.txt > Use this file to discover all available pages before exploring further. # External Interface > Learn how to define your contract's interface. export const File = ({children}) => { return children; }; export const Block = ({children}) => { return children; }; export const ExplainCode = ({children, languages}) => { const langList = typeof languages === 'string' ? languages.split(',') : languages || []; const [language, setLanguage] = useState(langList[0]); const [activeBlock, setActiveBlock] = useState(0); const [code, setCode] = useState(null); const blockRefs = useRef({}); const codeContainerRef = useRef(null); const ratioMap = useRef({}); const lang2label = { rust: '🦀 Rust', js: '🌐 JS', ts: '🌐 TS', python: '🐍 Python', go: '🐹 Go' }; const typeAccentClass = { state: 'border-l-4 border-emerald-500', warning: 'border-l-4 border-amber-500', note: 'border-l-4 border-amber-500' }; const accentBorder = t => typeAccentClass[t] || 'border-l-4 border-indigo-500'; function toRaw(ref) { const fullUrl = ref.slice(ref.indexOf('https')); const [url] = fullUrl.split('#'); const [org, repo, , branch, ...pathSeg] = new URL(url).pathname.split('/').slice(1); return `https://raw.githubusercontent.com/${org}/${repo}/${branch}/${pathSeg.join('/')}`; } async function fetchRaw(url, fromLine, toLine) { let res; if (typeof window !== 'undefined') { const validUntil = localStorage.getItem(`${url}-until`); if (validUntil && Number(validUntil) > Date.now()) { res = localStorage.getItem(url); } } if (!res) { try { res = await (await fetch(url)).text(); if (typeof window !== 'undefined') { localStorage.setItem(url, res); localStorage.setItem(`${url}-until`, String(Date.now() + 60000)); } } catch { return 'Error fetching code, please try reloading'; } } let lines = res.split('\n'); const from = fromLine ? Number(fromLine) - 1 : 0; const to = toLine ? Number(toLine) : lines.length; lines = lines.slice(from, to); const indent = lines.reduce((prev, line) => { if (!line.length) return prev; const m = line.match(/^\s+/); return m ? Math.min(prev, m[0].length) : 0; }, Infinity); return lines.map(l => l.slice(indent === Infinity ? 0 : indent)).join('\n'); } function parseHighlights(str) { const set = new Set(); if (!str) return set; String(str).split(',').forEach(part => { const [a, b] = part.trim().split('-'); if (b) { for (let i = Number(a); i <= Number(b); i++) set.add(i); } else if (a) set.add(Number(a)); }); return set; } const childArray = Array.isArray(children) ? children.flat(Infinity) : children ? [children] : []; const blocks = []; const files = []; for (const child of childArray) { if (!child || typeof child !== 'object' || !child.props) continue; if (child.props.highlights !== undefined) { let hl = {}; try { hl = JSON.parse(child.props.highlights); } catch {} if ((language in hl)) { blocks.push({ text: child.props.children, highlight: hl[language], fname: child.props.fname, type: child.props.type }); } } else if (child.props.language === language) { files.push({ ...child.props }); } } const activeFname = blocks[activeBlock]?.fname || files[0]?.fname; const fileKey = `${activeFname}-${language}`; const currentFile = files.find(f => f.fname === activeFname) || files[0]; useEffect(() => { setActiveBlock(0); setCode(null); ratioMap.current = {}; }, [language]); useEffect(() => { const observedEls = Object.entries(blockRefs.current).filter(([, el]) => el); const observer = new IntersectionObserver(entries => { entries.forEach(entry => { const idx = Number(entry.target.dataset.blockIdx); ratioMap.current[idx] = entry.intersectionRatio; }); let bestIdx = -1; let bestRatio = 0; Object.entries(ratioMap.current).forEach(([idx, ratio]) => { if (ratio > bestRatio) { bestRatio = ratio; bestIdx = Number(idx); } }); if (bestIdx !== -1) { setActiveBlock(bestIdx); } else { const zoneTop = window.innerHeight * 0.2; const allAboveZone = Object.entries(blockRefs.current).filter(([, el]) => el).every(([, el]) => el.getBoundingClientRect().bottom < zoneTop); if (allAboveZone) setActiveBlock(-1); } }, { threshold: [0, 0.1, 0.25, 0.5, 0.75, 1], rootMargin: '-20% 0px -50% 0px' }); observedEls.forEach(([idx, el]) => { el.dataset.blockIdx = idx; observer.observe(el); }); return () => observer.disconnect(); }, [blocks.length]); useEffect(() => { const container = codeContainerRef.current; if (!container) return; const firstHL = container.querySelector('[data-first-hl]'); if (!firstHL) return; const targetScrollTop = container.scrollTop + firstHL.getBoundingClientRect().top - container.getBoundingClientRect().top - container.clientHeight / 2 + firstHL.offsetHeight / 2; container.scrollTo({ top: Math.max(0, targetScrollTop), behavior: 'smooth' }); }, [activeBlock]); useEffect(() => { if (!currentFile?.url) return; setCode(null); const rawUrl = toRaw(currentFile.url); fetchRaw(rawUrl, currentFile.start, currentFile.end).then(setCode); }, [fileKey]); const startLine = currentFile?.start ? Number(currentFile.start) : 1; const highlighted = parseHighlights(blocks[activeBlock]?.highlight); const firstHlLine = highlighted.size > 0 ? Math.min(...highlighted) : -1; return
{}
{langList.map(lang => )}
{}
{}
{blocks.map((block, i) =>
{ blockRefs.current[i] = el; }} onClick={() => !block.type && setActiveBlock(i)} className={['px-5 py-4 rounded-md transition-all duration-200', block.type ? `cursor-default ${accentBorder(block.type)} opacity-75` : activeBlock === i ? `cursor-pointer ${accentBorder(block.type)} shadow-sm` : `cursor-pointer ${accentBorder(block.type)} opacity-60 hover:opacity-90`].join(' ')} style={{ backgroundColor: block.type ? 'var(--explain-card-bg)' : activeBlock === i ? 'var(--explain-card-active-bg)' : 'var(--explain-card-bg)', border: !block.type && activeBlock === i ? '1px solid var(--explain-card-border)' : '1px solid transparent' }}> {block.text}
)}
{} {currentFile &&
{}
{currentFile.fname}
View on GitHub
{}
{code === null ?
Loading...
: {code.split('\n').map((line, i) => { const lineNum = startLine + i; const isHL = highlighted.has(i + 1); return ; })}
{lineNum} {line || ' '}
}
}
; }; Smart contracts expose functions so users can interact with them. There are different types of functions including `read-only`, `private` and `payable`. ### Contract's Interface All **public** functions in the contract are part of its **interface**. They can be called by anyone, and are the only way to interact with the contract. Functions can also be exposed through trait implementations. This can be useful if implementing a shared interface or standard for a contract. This code generation is handled very similarly to basic `pub` functions, but the `#[near]` macro only needs to be attached to the trait implementation, not the trait itself: ```rust theme={"theme":{"light":"github-light","dark":"github-dark"}} pub trait MyTrait { fn trait_method(&mut self); } #[near] impl MyTrait for MyContractStructure { fn trait_method(&mut self) { // .. method logic here } } ``` ### Initialization Functions A contract can opt to have an initialization function. If present, this function must be called before any other to [initialize the contract](./storage). #### `@initialize({ privateFunction: true })` The initialization function is marked with the `@initialize` decorator. #### `#[init]` The initialization function is marked with the `#[init]` macro. #### `@init` The initialization function is marked with the `@init` decorator in Python. #### `@contract:init` The initialization function is marked with the `@contract:init` comment directive in Go. ### State Changing Functions The functions that modify the [state](./storage) or perform [actions](./actions) need to be called by a user with a NEAR account, since a transaction is required to execute them. #### `@call` State changing functions are marked with the `@call` decorator. #### `&mut self` State changing functions are those that take a **mutable** reference to `self` in Rust. #### `@call` State changing functions are marked with the `@call` decorator in Python. #### `@contract:mutating` State changing functions are marked with the `@contract:mutating` comment directive in Go. The SDK provides [contextual information](./environment), such as which account is calling the function, or what time it is. ### Read-Only Functions Contract's functions can be read-only, meaning they don't modify the state. Calling them is free for everyone, and does not require to have a NEAR account. #### `@view` Read-only functions are marked with the `@view` decorator in TS/JS. #### `&self` Read-only functions are those that take an **immutable** reference to `self` in Rust. #### `@view` Read-only functions are marked with the `@view` decorator in Python. #### `@contract:view` Read-only functions are marked with the `@contract:view` comment directive in Go. ### Private Functions Many times you will want to have functions that **are exposed** as part of the contract's interface, but **should not be called directly** by users. Besides initialization functions, [callbacks from cross-contract calls](./crosscontract) should always be `private`. These functions are marked as `private` in the contract's code, and can only be called by the contract itself. #### `decorator({privateFunction: true})` Private functions are marked by setting `privateFunction: true` in the `@call` or `@initialize` decorators. #### \[#private] Private functions are marked using the `#[private]` macro in Rust. #### Private Functions in Python In Python, you can create callbacks by using the `@callback` decorator, which is designed specifically for handling cross-contract call results. For general private functions that should only be called by the contract, you can use validation inside the function to check that the caller is the contract itself. ### Payable Functions By default, functions will panic if the user attaches NEAR Tokens to the call. Functions that accept NEAR Tokens must be marked as `payable`. Within the function, the user will have access to the [attached deposit](./environment). #### `@call({payableFunction: true})` Payable functions are marked by setting `payableFunction: true` in the `@call` decorator. #### \[#payable] Payable functions are marked using the `#[payable]` macro in Rust. #### Handling payments in Python In Python, you need to check the deposit manually using the Context API. There isn't a specific decorator for payable functions, so you'll need to verify the deposit amount in your function code. #### `@contract:payable` In Go, functions that accept attached NEAR tokens can be marked with the `@contract:payable` comment directive. You can optionally specify a minimum deposit requirement: `@contract:payable min_deposit=1NEAR`. This directive is compatible with `@contract:mutating` and `@contract:init`. ### Internal Functions All the functions we covered so far are part of the interface, meaning they can be called by an external actor. However, contracts can also have private internal functions - such as helper or utility functions - that are **not exposed** to the outside world. To create internal private methods in a JS contract, simply omit the `@view` and `@call` decorators. ### Internal Functions All the functions we covered so far are part of the interface, meaning they can be called by an external actor. However, contracts can also have private internal functions - such as helper or utility functions - that are **not exposed** to the outside world. To create internal private methods in a Rust contract, do not declare them as public (`pub fn`). ### Internal Functions All the functions we covered so far are part of the interface, meaning they can be called by an external actor. However, contracts can also have private internal functions - such as helper or utility functions - that are **not exposed** to the outside world. To create internal private methods in a Python contract, simply define normal methods without the `@view`, `@call`, or `@init` decorators. ### Internal Functions All the functions we covered so far are part of the interface, meaning they can be called by an external actor. However, contracts can also have private internal functions - such as helper or utility functions - that are **not exposed** to the outside world. To create internal private methods in a Go contract, simply define regular methods without any `@contract:` comment directives. Another way of not exporting methods is by having a separate `impl Contract` section, that is not marked with `#[near]`. ```rust theme={"theme":{"light":"github-light","dark":"github-dark"}} #[near] impl Contract { pub fn increment(&mut self) { self.internal_increment(); } } impl Contract { /// This methods is still not exported. pub fn internal_increment(&mut self) { self.counter += 1; } } ``` ### Pure Functions Pure functions are a special kind of function that do not require to access data from the state. They are useful to return hardcoded values on the contract. ```js theme={"theme":{"light":"github-light","dark":"github-dark"}} @NearBindgen({}) class Contract { helper_function(params... ){ // this function cannot be called from the outside } @view({}) interface_view(params...){ // this function can be called from outside } @call({privateFunction: true}){ // this function can be called from outside, but // only by the contract's account } } ``` ```rs theme={"theme":{"light":"github-light","dark":"github-dark"}} const SOME_VALUE: u64 = 8; #[near] impl MyContractStructure { fn internal_helper(&mut self, params... ){ // this function cannot be called from the outside } pub fn public_log(/* Parameters here */) { near_sdk::log!("inside log message"); } pub fn return_static_u64() -> u64 { SOME_VALUE } } ``` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} class Contract: def helper_function(self, params...): # This function cannot be called from the outside # as it has no decorator pass @call def validate_owner(self): if Context.predecessor_account_id() != self.owner_id: raise Exception("Only the owner can call this method") @view def get_static_value(self): # This function returns a hardcoded value return 42 ``` ```go theme={"theme":{"light":"github-light","dark":"github-dark"}} package main const SOME_VALUE uint64 = 8 // @contract:state type MyContract struct { Counter uint64 `json:"counter"` } // Internal helper — no @contract: directive, not exposed to the outside func (c *MyContract) doubleValue(n uint64) uint64 { return n * 2 } // @contract:view func (c *MyContract) GetStaticValue() uint64 { return SOME_VALUE } // @contract:view func (c *MyContract) GetDoubledCounter() uint64 { return c.doubleValue(c.Counter) } ```