Interacting with NCOG Earth Chain

Submitting Transactions: From a dApp or client perspective, interacting with NCOG is done via API endpoints exposed by NCOG nodes. Likely, NCOG nodes offer JSON-RPC endpoints (similar to Ethereum’s eth_sendTransaction, eth_call, etc.) or GraphQL/REST APIs to send transactions and query state. The steps to submit a transaction: 

1. Build the transaction object (specifying sender, recipient or contract call, any amounts, and payload data like contract method and parameters). 

2. Sign the transaction with the user’s Asset Wallet ML-DSA key (the wallet software typically handles this). 

3. Submit the signed transaction to an NCOG node via RPC (e.g., sendTransaction). 

4. Listen for transaction hash and confirmation events. 

For transactions that call the DDB, the process is the same on the frontend – you call a contract function or an RPC that triggers the stored procedure. Under the hood, the node will route it appropriately as described earlier, but the developer doesn’t necessarily need to manually separate it. However, developers should be aware that a DDB transaction might have a slightly higher latency (because of the two-phase commit). The SDK could abstract this by returning a promise/event when fully finalized. 

Gas Model: NCOG uses gas to meter computation and database usage. When submitting transactions, the developer must specify a gas limit and gas price (or accept defaults from nodes). For regular contracts, gas is consumed by instructions as usual. For DDB calls, gas might be measured in terms of normalized SQL operations or I/O bytes. The network may have a dual gas schedule: one for on-chain compute, one for database compute. This will be documented in the NCOG developer docs, but the key is that any operation that uses significant resources will require an appropriate gas limit and incur fees. If gas is insufficient, the transaction fails (rolled back) to avoid DoS. 

APIs and SDKs: NCOG is likely to provide developer SDKs in multiple languages (JavaScript/TypeScript, Python, etc.) to simplify interactions: 

• Web3-like library nec.js to handle account management, transaction encoding, event listening. 

• An extended API for Data Wallet interactions: e.g., a dApp can call window.ncog.requestData({fields: [“email”]}) if running in a browser with the NCOG Wallet extension. Mobile apps might use deep linking or wallet connect-style flows to request data or signatures from the wallet app. 

• Tools for contract deployment: a compiler and CLI to deploy smart contracts or database contracts. 

• Explorer and Dashboard: The NCOG Explorer will allow developers to inspect transactions, blocks, stored procedures execution results, etc. If a stored procedure fails endorsement, it might show up as a failed tx with an error code, which developers can debug. 

• Integration patterns for web and mobile: likely a browser extension wallet for web dApps (similar to MetaMask, but with dual wallet capabilities), and a mobile wallet that can handle deep link requests from mobile dApps. 

Using the Database in Apps: Developers writing dApps that leverage the DDB need to consider: 

• Defining Schema: They will write a database schema and include it in a special transaction to deploy it. This could be done through a migration script or schema file that the CLI takes and wraps into a deployment transaction. Once on-chain, the schema is set unless upgraded. 

• Stored Proc Development: Write stored procedures in the supported language. These procedures should be deterministic and side-effect free except for DB operations (no external API calls, etc., to ensure all validators get same result). They can include custom logic, loops, etc. The complexity is bounded by gas. 

• Testing: The developer can run a local NCOG node or a testnet that includes a DDB instance, or possibly use a stand-alone Postgres to test the stored procs logic, then ensure it behaves the same in the network environment. Given Postgres is standard, a lot of logic can be tested off-chain and then integrated. 

• Calling Procedures: From the dApp, calling a stored proc might be as easy as calling a contract method. Alternatively, an SDK might provide a direct method like ddb.call(“MyDatabaseContract”, “procedureName”, params) that under the hood constructs the proper transaction. After submission, the developer can wait for an event or callback. The result of a stored procedure (if it returns a value) is not directly returned to the caller like a function return (because of async tx processing), but it could be recorded in the database state or emitted as an event/log. For example, a proc could emit a blockchain event with its result or write to a “results” table that the front-end can query via a read call after confirmation. 

• Reading Data: For read-heavy applications, developers can use direct database queries. For instance, a web app might connect to a public API endpoint on a DDB validator that allows read queries (with certain rate limits or restrictions). NCOG might provide a query API where a client can send an SQL SELECT (or a predefined query) to a validator’s endpoint, and get the result. These queries do not go through the blockchain, they are off-chain reads, but thanks to the consensus, any up-to-date validator will have the latest committed data. If absolute trustless verification is needed, the app can request a proof or query multiple validators to cross-check results. 

Security Considerations for Developers: 

• When writing smart contracts, standard practices apply (careful with overflow, reentrancy, etc.) just as in other platforms. 

• When writing stored procedures, ensure to handle exceptions (if something should abort, use proper SQL exceptions so that the outcome is cleanly rolled back and the endorsement will fail gracefully). Also be mindful of the gas costs – e.g., a stored procedure with a complex JOIN over millions of rows might be too expensive. 

• Manage permissions: The database contract can enforce which user or role can call which procedure. The on-chain contract can check the message sender and apply logic accordingly (for example, only the user themselves or an admin NFT holder can call a certain proc). Because these checks happen in the contract interface before the DDB op is executed, they provide access control at the protocol level. 

• Data privacy: If certain data should not be exposed to all DDB validators (since they technically see plaintext when executing), one can opt to encrypt data at the application level as well and only store ciphertext in the DDB. But since DDB validators are somewhat like trusted execution peers (they’d get slashed for misbehavior and are likely semi-permissioned at least initially), many apps might be comfortable with storing moderately sensitive data in plaintext in the DDB. Extremely sensitive data can always be double-encrypted with a user key (and then even DDB validators only see gibberish, essentially treating the DDB as a distributed secure storage – albeit then your smart procedures can’t operate on the plaintext). So developers have flexibility on that spectrum. 

Integration with Other Chains and Legacy Systems: NCOG Earth Chain can connect to external systems via: 

• The NEC Multi-Chain Bridge allows moving assets between NCOG and other blockchains. Developers can incorporate cross-chain functionality (for example, accept Ethereum tokens via the bridge and then use them in a NCOG DApp). 

• Off-chain oracles can feed data into NCOG (an oracle can be a special account that writes to the DDB or a contract, e.g., posting price feeds or real-world data). Because NCOG can handle data well, one could even feed bulk data (like daily climate sensor readings into the DDB) efficiently. 

• Traditional applications can interface with NCOG via its APIs. For instance, an enterprise could run an NCOG validator and use the PostgreSQL interface as if it were talking to a regular database, with the benefit that each transaction is globally replicated and consensus-checked. This could ease adoption since many enterprise developers know SQL – they can effectively “code to SQL” and let NCOG handle the blockchain aspects in the background. 

Tools: We expect a suite of tools including: 

• CLI tool for deploying contracts and managing accounts (like ncog-cli deploy MyContract.sol or for deploying DB schema). 

• Explorer (web UI) to inspect blockchain state, contract state, table contents (maybe read-only). Possibly a specialized explorer section for the DDB tables of a contract, which is novel. 

• Monitoring: For validators, NCOG likely provides telemetry on performance (TPS, memory, etc.), which developers of high-throughput dApps might monitor to understand network load. 

• Testnet: A public testnet where devs can test their contracts and procedures with fewer tokens and perhaps different performance parameters. 

Example Walk-Through: Suppose you want to build a decentralized marketplace on NCOG: 

1. Define data structures: You create a database contract MarketplaceDB with tables: Listings(itemId, seller, price, description) and Purchases(orderId, itemId, buyer, status). You also have standard token handling using $NEC or a stablecoin. 

2. Write stored procedures: e.g., createListing(item, price, desc), purchaseItem(itemId), updateOrderStatus(orderId, status). The purchaseItem proc might check token payment (perhaps by requiring the buyer to escrow tokens or by interacting with an escrow contract), then insert a row in Purchases and mark the listing as sold. 

3. Deploy: You deploy the MarketplaceDB contract with the schema and procs. You deploy a standard ERC-20-like contract for a stablecoin if needed (or use an existing one). 

4. Frontend: You build a dApp UI. Users connect with NCOG Wallet. When a user creates a listing, the dApp calls the createListing proc via an RPC call. The user’s wallet pops up to sign the transaction. The tx goes to NCOG, DDB nodes execute it (inserting the row). Finality comes back ~1 second later. The item now appears in the global listing (the front-end can query the DDB for all listings or subscribe to an event). 

5. When a buyer wants to buy, the dApp calls purchaseItem. The wallet might prompt two things: a token transfer approval and the procedure call. Once confirmed, the procedure runs, perhaps moving tokens into escrow (which could be done by an atomic call to a token contract if integrated or by trusting the procedure logic combined with a token transfer in the same block). The purchase is recorded. 

6. The seller ships the item and later calls updateOrderStatus(orderId, “shipped”) – another DDB call. 

7. Meanwhile, the marketplace contract could allow the buyer to dispute if not received, etc., all recorded in the DDB. Finally, mark complete and trigger release of escrow (which could be a separate contract function call). 

Throughout this, the developer uses NCOG’s parallelism: listing and purchases can be happening concurrently without blocking each other, thanks to separate mempool handling if needed. Also, large descriptions or images for items can be stored off-chain encrypted via Data Wallet, with just a reference in the DDB. The Data Wallet could allow the seller to attach an encrypted image of the item that only buyers who purchase get the key for (delivered via their Data Wallet) – enabling a kind of DRM or private content delivery. 

This scenario shows how the pieces (smart contracts, DDB, dual wallet) can come together to build a more feature-rich dApp than one could easily build on a vanilla blockchain. 

Documentation and Community: As a developer, you’ll have access to NCOG’s documentation portal (which this text is part of) with detailed references on the API, tutorials, and example code. The community forums and support channels will be active, especially given the novel aspects (like if you encounter an error in a stored procedure endorsement, the community/maintainers can help interpret it). 

To conclude the developer guide: NCOG Earth Chain offers a familiar development experience extended with new superpowers. You still write smart contracts and transact with keys, but you also can use SQL and manage user data in ways not possible on other chains. The platform’s design abstracts a lot of complexity (like the two-phase consensus) so developers can focus on business logic. By following best practices and using the provided SDKs, developers can build scalable, secure, and user-friendly decentralized applications that leverage the full potential of NCOG’s architecture.