OnFinality
New RPC users get 35% off their first monthView the offer
OnFinality Learn
Integration & Development8 min read

Confidential Flag in Blockchain Applications: Meaning, Implementation, and Verification

Understand what a confidential flag can and cannot do, then implement privacy-aware metadata and verify its behavior through an RPC endpoint.

TL;DR

A confidential flag is usually an application-defined marker that tells software to treat a record, request, or transaction as sensitive; it is not automatically encryption or on-chain privacy. Public blockchain protocols generally do not provide a universal JSON-RPC field named confidential, so the flag must be defined by the application, smart contract, wallet, indexer, or privacy-enabled protocol. This guide explains the mental model, shows implementation patterns using placeholders such as RPC_URL and PRIVATE_KEY, and provides a reproducible verification procedure. It also identifies the security limits of a flag and the controls required when confidentiality is a real requirement.

Meaning and scope of a confidential flag

A confidential flag is a Boolean or enumerated value that changes how software handles data. For example, an application might set confidential: true to suppress sensitive fields from logs, restrict access in an API, select an encrypted payload, or instruct an indexer not to expose optional metadata. The exact behavior comes from the system that defines the field.

The flag itself is not a privacy primitive. If a plaintext value is published in a transaction input, event, calldata field, block, or public database, adding a confidential marker does not hide it. Anyone with access to that public data can still inspect, copy, and archive it.

For ordinary blockchain RPC, treat confidential as application metadata unless the network's protocol documentation explicitly defines a cryptographic privacy mechanism. This distinction prevents a common design error: assuming that a label changes the visibility of data after publication.

  • Marker: records intended handling policy.
  • Encryption: transforms data so unauthorized readers cannot understand it.
  • Access control: determines who may retrieve or decrypt it.
  • Confidential transaction protocol: changes how transaction contents or state are revealed.

Protocol boundaries and data visibility

Most standard blockchain JSON-RPC methods describe transport and ledger operations, such as retrieving blocks, submitting transactions, or reading contract state. A provider may forward a request containing custom application fields, reject them, or ignore them according to the node and middleware implementation. You should not infer network support from a field name alone.

Before using the flag, identify where it is defined: a smart-contract ABI, a wallet SDK, an API schema, an indexer, a private transaction service, or a network-specific privacy feature. The authoritative source should specify accepted values, default behavior, whether the field is persisted, and which parties can observe it.

For public EVM-compatible networks, a contract can store a flag in state or emit it in an event, but both the state transition and event are generally observable. A private RPC route can protect transport between your application and a provider, but it does not necessarily make the resulting blockchain state private.

  • Document the field owner and version before integrating it.
  • Separate transport confidentiality from ledger confidentiality.
  • Check whether logs, traces, mempool data, and indexer databases expose the marked content.
  • Use a network-specific guide from the supported networks directory when privacy behavior depends on a particular chain.

Security model and threat assumptions

Define what must remain confidential before choosing an implementation. The threat may be an external observer, a public indexer, another application user, a compromised RPC credential, or an operator with access to logs. A single Boolean cannot address all of these threats.

A useful model separates four locations: the client, the RPC transport, the pending transaction or mempool, and finalized chain data. TLS protects the connection to an HTTPS endpoint, but the endpoint operator may still process the request. Once plaintext data enters a public transaction or event, later encryption or redaction cannot restore confidentiality.

Write an explicit policy for each field. For example, public identifiers may be stored on-chain; sensitive values may be encrypted client-side; a commitment or hash may be published for later verification; and the decryption key may be distributed through an authenticated off-chain service. Avoid treating a hash as automatically private: low-entropy inputs can be guessed and compared.

  • Confidentiality target: who must not see the value?
  • Retention target: how long must it remain protected?
  • Integrity target: must readers prove that the value was not changed?
  • Availability target: who can recover the value if the original client is unavailable?

Application-level implementation pattern

For a conventional application, define the flag in a versioned schema rather than placing an undocumented property beside a standard RPC parameter. A practical record can contain a public record identifier, a policy version, a Boolean or mode, a ciphertext or commitment, and an off-chain reference. The application then enforces the policy consistently at ingestion, storage, logging, and retrieval.

Do not send private values to an untrusted endpoint merely because the request includes confidential: true. If the value must not be visible to the RPC operator, encrypt it before the request is created. Keep keys outside source control and avoid putting them in browser bundles or transaction calldata.

The following example sends an application-defined JSON document to an API route. It is not a standard blockchain JSON-RPC method; replace RPC_URL with a route that your own service documents. The example demonstrates the flag's semantics without claiming that a node will enforce them.

  • Validate schemaVersion and reject unknown policy modes.
  • Redact the payload and credentials from application logs.
  • Return an explicit policy result, such as accepted, rejected, or unsupported.
  • Test both the confidential and non-confidential paths.
curl -X POST "$RPC_URL/v1/records" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_TOKEN" \
  --data '{
    "schemaVersion": 1,
    "confidential": true,
    "payload": "CLIENT_SIDE_CIPHERTEXT",
    "commitment": "OPTIONAL_COMMITMENT"
  }'

On-chain representation and contract verification

If a contract needs to record that a workflow follows a confidentiality policy, store only the minimum public metadata. A Solidity contract might record a Boolean and a commitment, but the Boolean remains public and does not conceal the committed value. The commitment proves consistency only when the underlying value and nonce are later revealed and checked.

When the flag is part of a transaction, verify the actual contract behavior rather than relying on a wallet display or SDK property. Confirm the ABI encoding, emitted event, receipt status, and resulting state. If a contract ignores an extra client-side field, the transaction may still succeed while the intended policy is never recorded.

The following JavaScript uses an EVM-compatible JSON-RPC endpoint through ethers. It reads a contract's public flag and commitment after deployment. Replace the placeholders with values from your deployment; do not put a private key in frontend code.

  • Confirm the contract address and chain ID before reading state.
  • Compare the returned flag with the transaction input or deployment configuration.
  • Treat the returned commitment as public metadata, not as the secret itself.
  • Use RPC endpoint documentation to distinguish endpoint configuration from contract behavior.
import { ethers } from "ethers";

const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
const contract = new ethers.Contract(
  process.env.CONTRACT_ADDRESS,
  [
    "function confidential() view returns (bool)",
    "function commitment() view returns (bytes32)"
  ],
  provider
);

const [confidential, commitment] = await Promise.all([
  contract.confidential(),
  contract.commitment()
]);

console.log(JSON.stringify({ confidential, commitment }, null, 2));

RPC request and response inspection

When the flag is implemented by middleware or an API gateway, inspect the raw request and response before debugging the chain. A successful HTTP response can still contain an application-level rejection, while a JSON-RPC error can indicate that the method or parameter is unsupported.

Use a minimal request first, then add the confidential field and compare the responses. Record the HTTP status, JSON-RPC error object, request identifier, returned policy state, and any transaction hash. Never paste API tokens, private keys, plaintext secrets, or signed raw transactions into shared tickets.

This Python example compares two documented application calls. It assumes the service accepts a method named by your own API contract; it does not claim that all blockchain nodes implement setConfidentialFlag.

  • Use a unique request ID when correlating retries and provider logs.
  • Check whether the endpoint expects positional or named parameters.
  • Compare the response schema, not only the HTTP status.
  • Run tests against a development record before using production identifiers.
import os
import json
import requests

rpc_url = os.environ["RPC_URL"]
headers = {"Content-Type": "application/json"}

def call(params):
    body = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "setConfidentialFlag",
        "params": params
    }
    response = requests.post(rpc_url, headers=headers, json=body, timeout=20)
    response.raise_for_status()
    result = response.json()
    if "error" in result:
        raise RuntimeError(json.dumps(result["error"]))
    return result["result"]

print("without flag:", call({"recordId": os.environ["RECORD_ID"], "confidential": False}))
print("with flag:", call({"recordId": os.environ["RECORD_ID"], "confidential": True}))

Verification results and measurement procedure

A reliable test demonstrates both semantics and exposure. Create two otherwise equivalent test records: one with the flag disabled and one with it enabled. Use a non-sensitive payload or a locally generated test secret, then inspect the client logs, gateway logs, RPC response, transaction receipt, contract event, public explorer or node query, and downstream indexer.

Capture results in a table rather than relying on a dashboard label. Leave measured values blank until the test is run in your environment. A useful results table has these columns: Test, Expected behavior, Observed result, Evidence, and Pass/Fail. Recommended rows include API acceptance, state change, event visibility, payload exposure, retry behavior, and unauthorized retrieval.

For performance, repeat each case under the same request size and concurrency. Measure client-perceived latency, error rate, confirmation delay, and payload size separately. Do not compare providers or networks from one uncontrolled run; record chain, region, software version, block state, concurrency, and timestamp.

  • API acceptance: the documented route accepts the mode or returns a clear unsupported error.
  • Persistence: the intended state or metadata is present after confirmation.
  • Exposure: the sensitive value is absent from every location where policy requires protection.
  • Access control: an unauthorized identity cannot retrieve or decrypt the value.
  • Recovery: an authorized identity can recover the value using the documented key process.

Failure modes and troubleshooting paths

If a request returns an invalid-parameter error, check the API or contract schema first. The name confidential is not enough to establish support. Some systems reject unknown fields; others ignore them, which is more dangerous because the caller may assume protection that never occurred.

If the flag appears in an application response but not in chain state, determine whether it is only gateway metadata. Inspect the signed transaction, receipt, event topics, and contract storage. If the value is present in calldata or an event, consider it public even if the user interface masks it.

If confidentiality fails intermittently, inspect retries, asynchronous workers, queue payloads, tracing systems, and dead-letter storage. Sensitive data often leaks outside the primary database. Rotate exposed credentials or encryption keys according to your incident procedure; changing the flag alone is not remediation.

If reads disagree across endpoints, compare the chain ID, block tag, finalized state, and provider response. A recent transaction may not be visible at the same time to every read path. See the RPC reliability and consistency guide for a structured approach to endpoint discrepancies.

  • Unsupported field: remove the field or implement it at the documented application layer.
  • Ignored field: fail closed and require an explicit acknowledgement from the server.
  • Public plaintext: treat the value as disclosed and rotate or revoke it where possible.
  • Stale state: compare block numbers and wait for the required confirmation policy.
  • Leaking logs: redact at the source and review retained telemetry and backups.

Design tradeoffs and operational limits

A public marker is easy to index, audit, and integrate, but it provides no secrecy. Client-side encryption offers stronger control over plaintext exposure, yet introduces key management, recovery, rotation, and revocation responsibilities. Commitments preserve verifiability while hiding the value from casual observers, but they can be brute-forced when inputs are predictable.

A privacy-enabled network or confidential execution environment may reduce public visibility, but its guarantees depend on the protocol, trusted components, validator or operator assumptions, and read-access model. Review the network's security documentation instead of treating a provider's endpoint as evidence of confidentiality.

Operationally, privacy controls can increase latency, payload size, failure recovery complexity, and support burden. Define the minimum necessary confidential scope. Publicly store status, timestamps, and commitments where appropriate, and keep sensitive business data in a purpose-built encrypted system when on-chain storage is not required.

When choosing infrastructure, compare documented network access, authentication, limits, and observability rather than assuming a provider changes protocol privacy. The RPC service overview and RPC pricing information can help with infrastructure planning; they do not replace application-level encryption or access control.

Implementation checklist and next steps

Start by writing the confidentiality policy in plain language: what is protected, from whom, for how long, and what evidence must remain public. Then map every copy of the data across the client, RPC request, transaction, logs, queues, databases, indexers, backups, and user interface.

Next, define a versioned schema and fail-closed behavior for unsupported modes. Encrypt sensitive values before transmission when the RPC operator should not see them, publish only the minimum commitment or status required for verification, and test unauthorized access with an identity that has no decryption permission.

Finally, run the results-table procedure in a development environment and retain the evidence needed to reproduce it. For broader infrastructure decisions, consult the multi-chain RPC endpoints guide, review dedicated node options, and use RPC Assistant for a short, network-specific endpoint recommendation when the endpoint choice—not the confidentiality design—is the remaining decision.

  • Document whether the flag is application metadata, contract state, or protocol functionality.
  • Keep secrets and private keys in environment-managed secret storage.
  • Verify receipts, events, state, logs, and indexer exposure independently.
  • Measure only after defining the test environment and acceptance criteria.
  • Treat a confidential flag as a policy signal unless cryptographic privacy is explicitly documented.

Never Worry about Infrastructure Again

OnFinality takes away the heavy lifting of DevOps so you can build smarter and faster.

Get Started