What this page is actually for

The corrected architecture

Program = deployed runtime object

Read vs write is the first mental split

Create the project

1. Install and run the Octra web client, then open the local browser UI. Official docs describe the client at 127.0.0.1:8420 by default.
2. Open Dev Tools in the client. This is where the first-program flow lives.
3. Create a project from the existing ocs-01 token template. Do not start from a blank contract for the first run.
4. Keep both generated files: main.aml and interfaces/IOCS01.aml. The main token file imports the interface.
5. Read the template before editing. Identify token metadata, total supply, decimals, owner, balances, grants, transfer, grant, pull, balance_of, allowance, and get_* methods.
6. For the first deploy, do not customize behavior. Prove the default path works before changing source.

Compile and inspect

1. Set language to AppliedML (.aml).
2. Click compile. If compilation fails, stop. Do not deploy half-understood code.
3. Inspect ABI. This is the frontend method map: method names, params, view/write shape.
4. Inspect Assembly or disassembly. This shows how readable source lowers into VM behavior.
5. Inspect Console for compiler errors/warnings and output metadata.
6. Inspect Storage after deployment/calls to verify state changed the way source says it should.

Deploy

1. Enter constructor params as a JSON array, for example ["MyToken", "MTK", 1000000000000, 6].
2. Understand the positions: name, symbol, raw total supply, decimals. Keep order exact.
3. Click preview address. This computes the expected deployed address without publishing the program.
4. Review deploy fee, deployer account, bytecode field, and constructor params.
5. Click deploy. Deployment submits bytecode and runs the constructor.
6. Copy the resulting program address. This is now the contract your app will read and call.

Call and verify

1. Use read-only calls first: get_name [], get_symbol [], get_total_supply [], balance_of ["your_address"].
2. Confirm the deployer received initial supply. In the template, initial supply is assigned during constructor initialization.
3. Send a small transfer: method transfer, params ["recipient_octra_address", 1000], native OCT amount 0.
4. Track the transaction: submitted/staging is not the same as final confirmation.
5. Re-read sender and recipient balance_of. Confirm Storage and receipts match expectations.
6. Use source verification with the same project files: main.aml and interfaces/IOCS01.aml.

SDK comes after the contract path is clear

SDK adapter surface

Data model for optional wallet approval UI

type WalletState =
  | "unsupported"
  | "missing"
  | "disconnected"
  | "connecting"
  | "connected"
  | "wrong_network"
  | "approval_requested"
  | "rejected"
  | "submitted"
  | "staging"
  | "confirmed"
  | "failed";

type ContractCallTicket = {
  programAddress: string;
  method: "transfer" | "grant" | "pull" | string;
  params: unknown[];
  nativeAmount: "0";
  feeEstimate?: string;
  privacyMode: "public" | "private";
};

What Cursor/Claude/Codex should build after contracts work

1. Keep the contract adapter first: deployed address, ABI, read methods, write tickets, receipts.
2. Create a wallet adapter file and a mock implementation behind an explicit dev flag.
3. Build the account header: wallet detected, connected address, network, copy address, disconnect.
4. Build an action ticket before any chain call: method, params, fee, privacy mode, state.
5. Add rejection and failure states. A user rejecting approval is not an app crash.
6. Only after this works, wire OCS-01 reads and writes into the adapter.
7. Only after public calls work, add PVAC for private data preparation.

What webcli is for

Concrete webcli facts to know

How to use webcli while designing the dApp

1. Install and run the client from the official docs. Treat it as the known-good Octra account surface.
2. Create or import a wallet, then inspect the public balance, pending balance, nonce, and transaction history.
3. Perform a simple public send so you understand address, amount, fee, nonce, and confirmation behavior.
4. Try encrypt/decrypt balance flows and write down the user-visible states. Those states become your private DeFi UI queue.
5. Inspect local JSON-RPC examples so your frontend mental model matches the network method groups.
6. Use OCS-01 dev tools after that, so token program calls feel like an extension of the wallet flow, not a separate universe.

UI components webcli implies

• account summaryAddress, balance, pending/private balance, nonce, network, copy/export actions.
• transaction composerRecipient, amount, fee, nonce, preview, send, submitted, confirmed.
• privacy operationsEncrypt balance, decrypt balance, private send, proof/pending states, stealth address labels.
• history tableHash, type, value, status, timestamp, sender/recipient, privacy mode.
• RPC inspectorDeveloper-only surface for method, params, response, latency, error body.
• safety railNever ask users to paste secrets into a dApp just because webcli has local wallet management.

AppliedML concepts inside OCS-01

Read the file like this

1. Open interfaces/IOCS01.aml first. This is the contract's public API and the best frontend checklist.
2. Open main.aml and identify the state block. Every state field needs either a UI surface, a dev inspector row, or an intentional reason to stay hidden.
3. Find the constructor. Constructor params are deployment-time product decisions: token name, symbol, raw supply, decimals.
4. Separate view fn from fn. Reads are query UX; writes are approval and transaction UX.
5. Find each require. Each check is a future validation message in the app.
6. Find each emit. Each event is a future activity-row type.
7. Compile and inspect ABI, Assembly, Console, and Storage. The source is readable, but the lowered output shows execution truth.

Annotated AppliedML token skeleton

import "./interfaces/IOCS01.aml"

program Token implements IOCS01 {
  // Persistent data. This becomes storage.
  state {
    name: string
    symbol: string
    total_supply: int
    decimals: int
    owner: address
    balances: map[address]int
    grants: map[address]map[address]int
  }

  // User-facing history. This becomes an activity row.
  event Transfer(from: address, to: address, amount: int)

  // Deployment-time initialization.
  constructor(name_: string, symbol_: string, supply_: int, decimals_: int) {
    self.name = name_
    self.symbol = symbol_
    self.total_supply = supply_
    self.decimals = decimals_
    self.owner = origin
    self.balances[origin] = supply_
  }

  // Read-only API. No signing prompt should be required.
  view fn balance_of(addr: address): int {
    return self.balances[addr]
  }

  // State-changing API. Needs wallet approval and receipt tracking.
  fn transfer(to: address, amount: int): bool {
    require(amount > 0, "amount must be positive")
    require(self.balances[caller] >= amount, "insufficient balance")

    self.balances[caller] = self.balances[caller] - amount
    self.balances[to] = self.balances[to] + amount

    emit Transfer(caller, to, amount)
    return true
  }
}

How compilation teaches you AppliedML

Beginner exercises

1. Deploy the unedited OCS-01 template once. Do not customize it yet. Learn the happy path first.
2. Change only token name and symbol. Recompile and verify which ABI parts do not change.
3. Change decimals and supply. Learn raw units by comparing total supply display against human token display.
4. Add or rename an event in a local experiment. Watch how the activity model changes.
5. Add a stricter require. Make the frontend show that error before submission where possible.
6. Inspect Storage before and after transfer, then make the UI refresh exactly those balances.

Mistakes to teach against

• confusing caller and originAsk who directly called the program versus who initiated the transaction path.
• ignoring decimalsHuman display units and raw integer units are different. Show both in dev mode.
• treating reads as writesRead-only methods should not trigger approval UX.
• hiding require failuresEvery runtime check should have a matching validation or error surface.
• trusting source onlyCompile output, ABI, assembly, and storage are part of the truth.
• inventing ABI methodsAgents should read the ABI or interface, not hallucinate wallet or contract calls.

Why "program" matters

Why OCS-01 is the first example

What Octra says to do first

1. Open the Octra client dev tools and create a project from the ocs-01 token template.
2. Keep both generated files: main.aml and interfaces/IOCS01.aml. The main file imports the interface.
3. Compile as AppliedML (.aml) and inspect the generated ABI, Assembly, Console, and Storage tabs.
4. Use constructor params as a JSON array, for example ["MyToken", "MTK", 1000000000000, 6].
5. Preview address, deploy, then call read methods like get_name, get_symbol, get_total_supply, and balance_of.
6. Send a small transfer call with OCT amount set to 0, because you are calling the token program, not sending native OCT with the call.
7. Verify source after deployment so the deployed program can be linked back to the exact source files.

Read OCS-01 as a UI spec

Minimal OCS-01 shape

program Token implements IOCS01 {
  state {
    balances: map[address]int
  }

  event Transfer(from: address, to: address, amount: int)

  constructor(supply: int) {
    self.balances[origin] = supply
  }

  view fn balance_of(addr: address): int {
    return self.balances[addr]
  }

  fn transfer(to: address, amount: int): bool {
    let bal = self.balances[caller]
    require(bal >= amount, "insufficient balance")
    self.balances[caller] = bal - amount
    self.balances[to] = self.balances[to] + amount
    emit Transfer(caller, to, amount)
    return true
  }
}

What the UI must not hide

• constructor paramsToken name, symbol, raw supply, and decimals are positional. The wrong order breaks deployment.
• ABI truthUse ABI output as the source of callable methods. Do not invent method names in components.
• raw unitsDisplay human units, submit raw units, and show the conversion in the review ticket.
• call modeRead methods use view calls. State changes use send call tx and need wallet approval.
• receipt stateAcceptance into staging is not final confirmation. The activity table needs both states.
• verificationVerified source gives builders and users confidence that the UI matches the deployed program.

What happens when you press transfer

What happens when you press grant

What the user should understand

What the developer should instrument

The boundaries

Do not mix them up

@0xio/pvac quick shape

import {
  PvacContext,
  initPvac,
  buildEncryptPayload,
  buildDecryptPayload
} from "@0xio/pvac";

const wasm = await initPvac();

const ctx = await PvacContext.create(seed, wasm, {
  preWarm: true,
  threads: navigator.hardwareConcurrency
});

const encrypted = ctx.fullEncrypt(1000000);
const cipher = encrypted.cipherB64;          // hfhe_v1|base64
const proof = encrypted.boundProofEncoded;   // zkzp_v2|base64

const encryptTxData = buildEncryptPayload(ctx, 1000000);
const decryptTxData = await buildDecryptPayload(
  ctx,
  500000,
  currentCipher,
  currentBalance
);

What devs need to know about PVAC

• browser onlyRuns in web dApps, browser extensions, and web workers. Not supported on Node.js servers.
• WASM bundledThe README says the WASM module is bundled, so no separate setup is required for the package itself.
• seed mattersContext creation expects a 32-byte seed from wallet key derivation. Do not invent your own unsafe key flow.
• proofs can be slowRange proofs can take tens of seconds. UI needs progress, cancellation language, and patience.
• headers matterParallel proof generation needs SharedArrayBuffer plus COOP/COEP headers for rayon thread pool parallelism.
• memory mattersPlan for around 100MB RAM during PVAC context initialization according to the package README.

SDK reminder before PVAC

How to think about @0xio/pvac

Public token transfer

1. Read token metadata from OCS-01: get_name, get_symbol, get_total_supply, decimals from the contract/template.
2. Read the connected account balance with balance_of and format raw units for display.
3. User enters recipient and amount. UI converts human amount to raw units and validates address, decimals, and balance.
4. Action ticket shows program address, method transfer, params, OCT amount 0, fee estimate, and settlement path.
5. Request 0xio wallet approval through the SDK adapter. Never collect secrets in the app.
6. Submit, show staging, poll transaction or receipt, then refresh balances and activity after confirmation.

Private DeFi action

1. Connect wallet and initialize PVAC only for actions that require encrypted values or proofs.
2. Encrypt the user amount locally. The UI says "encrypting locally", not "loading".
3. Create a bound proof if the program needs to prove the ciphertext matches a committed amount.
4. Use cipher arithmetic when the app must compute new encrypted balances or reserve deltas.
5. Create range proofs when the program needs non-negative balance or reserve guarantees.
6. Submit ciphertexts and proofs to the program through the wallet-approved transaction flow.

Why private DeFi changes the app shape

How to stage the build

1. Build the OCS-01 public wallet first: connect, read metadata, read balance, transfer, activity table.
2. Add allowance/delegation UI: grant, allowance read, pull, revoke or reset if the contract supports it.
3. Add a mock private action queue with named states before adding cryptography.
4. Add PVAC initialization and capability checks: browser, WASM, SharedArrayBuffer, memory expectations.
5. Wire encryption and proof generation behind a privacy adapter, then connect it to wallet-approved submission.
6. Only after that, design private swap/lending/portfolio features. Otherwise you will mix product logic and cryptographic plumbing too early.

Contract rule

GitHub peer review checklist

1. Publish the repository with main.aml, interfaces, tests, README, and exact deployed program address.
2. Include constructor params and explain raw units, decimals, owner/deployer assumptions, and network.
3. Commit generated ABI or provide a reproducible compile command so reviewers can compare source to deployed behavior.
4. Document every public method: who can call it, what state it changes, what it emits, and how it can fail.
5. Ask peers to review invariants, edge cases, malicious callers, overflow/underflow assumptions, grants/allowances, and revert paths.
6. Do not market the contract as safe until review feedback is addressed and the source is verified against deployment.

Code is cheap

GTM is key for success

Prompt 2: add SDK adapter

Create a small @0xio/sdk adapter for this app.

Interface:
- detectWallet()
- connectWallet()
- getAccount()
- readBalance(address)
- requestContractCall({ programAddress, method, params, amount, fee })
- waitForTransaction(hash)

Rules:
- no SDK calls inside React components except through this adapter
- no secret key handling in app code
- preserve disconnected, connecting, approving, submitted, confirmed, rejected, failed states
- verify exact SDK imports from local package types before using them

Prompt 3: add PVAC privacy adapter

Add a browser-only @0xio/pvac adapter for encrypted DeFi actions.

Use PVAC for:
- initPvac()
- PvacContext.create(seed, wasm, options)
- fullEncrypt(amount)
- buildEncryptPayload(ctx, amount)
- buildDecryptPayload(ctx, amount, currentCipher, currentBalance)
- ctAdd / ctSub for ciphertext arithmetic where needed
- bound proof and range proof states

UI requirements:
- show "initializing PVAC"
- show "encrypting locally"
- show "building proof"
- show "waiting for wallet approval"
- show "submitted"
- show "confirmed" or "failed"

Constraints:
- browser only, no Node.js server usage
- proof generation may be slow, so do not block the whole UI
- if SharedArrayBuffer/COOP/COEP are missing, show a slower-mode warning

Prompt 4: review like DevRel

Review this Octra/0xio dApp as a DevRel engineer.

Find:
- any place the app invents wallet APIs
- any place the app asks for user secrets
- any missing transaction states
- any OCS-01 raw unit / decimals mistakes
- any view call vs state-changing call confusion
- any PVAC proof state hidden behind generic loading UI
- any AI-generated contract logic that lacks tests, source verification, or peer review path
- any mobile layout overflow for addresses, hashes, errors, or method names

Return findings with file and line references, then patch the highest-impact issues.

What was verified

Octra docs describe Octra as an FHE blockchain network, Applied programs as deployable units with state, entrypoints, checks, events, constructor logic, ABI and lowered output, and the first-program flow as an OCS-01 token template with main.aml, interfaces/IOCS01.aml, compile, deploy, call, transfer, and verify steps.

Package versions checked

@0xio/pvac latest was checked from npm as 1.0.0, described as PVAC-HFHE privacy primitives for Octra Network: FHE encryption, range proofs, and cipher arithmetic. The SDK package listing describes @0xio/sdk as the official TypeScript SDK for 0xio Wallet and Octra dApp integration.