Skip to content

docs: document on-chain contract integration and testnet setup - #1696

Open
maxx-GENIUS wants to merge 1 commit into
DistinctCodes:mainfrom
maxx-GENIUS:docs/onchain-integration-guide
Open

maxx-GENIUS wants to merge 1 commit into
DistinctCodes:mainfrom
maxx-GENIUS:docs/onchain-integration-guide

Conversation

@maxx-GENIUS

Copy link
Copy Markdown

Problem

Currently, there is no comprehensive documentation connecting how the backend and frontend interact with the Soroban contracts. Contributors lacked clear guidance on:

  • Which contract functions are invoked during the asset lifecycle (registration, governed transfer, tokenization).
  • Required environment variables across backend and frontend (ASSETSUP_CONTRACT_ID, STELLAR_SECRET_KEY, SOROBAN_RPC_URL, network passphrases).
  • How contracts/deployments/<network>.json is consumed across services.
  • How transaction failure codes map to the numeric allocations in contracts/ERRORS.md.
  • How client-side wallet signing (Freighter / Stellar Wallets Kit) relates to backend operator signing.
  • How a new contributor can fund an account and register an asset on testnet.

Solution

  1. Added docs/onchain-integration.md:

    • Architectural Overview: Outlines the role of all 5 contracts (assetsup, contrib, multisig-wallet, multisig-transfer, asset-maintenance).
    • Sequence Diagrams: Added Mermaid sequence diagrams for (1) Asset Registration, (2) Governed Ownership Transfer via multisig-transfer, and (3) Asset Tokenization.
    • Dual-Signer Architecture: Clarified separation between server-side operator signing (STELLAR_SECRET_KEY) and user-authenticated wallet signing (Freighter).
    • Environment Configuration: Complete reference tables for backend/.env and frontend/.env.local.
    • Deployment Artifacts: Documented consumption of deployments/<network>.json.
    • Error Taxonomy Mapping: Direct mapping of runtime Error(Contract, #XYZ) status codes to contracts/ERRORS.md blocks.
    • Step-by-Step Testnet Walkthrough: Concrete CLI commands for funding with Friendbot, deploying, invoking register_asset, and verifying on testnet.
  2. Updated Root README.md:

    • Added a Documentation section linking directly to docs/onchain-integration.md, contracts/README.md, and contracts/ERRORS.md.

Closes #1657

Add `docs/onchain-integration.md` detailing how the backend and frontend
integrate with the Soroban smart contracts (`assetsup`, `contrib`,
`multisig-wallet`, `multisig-transfer`, `asset-maintenance`). Include
Mermaid sequence diagrams for asset registration, governed transfer, and
tokenization, environment configuration tables, deployment manifest
consumption, error code mapping to `contracts/ERRORS.md`, dual-signer
architecture (Freighter wallet vs backend operator), and a step-by-step
testnet walkthrough for registering an asset.

Closes DistinctCodes#1657
@vercel

vercel Bot commented Oct 26, 2026

Copy link
Copy Markdown

@maxx-GENIUS is attempting to deploy a commit to the naijabuz's projects Team on Vercel.

A member of the Team first needs to authorize it.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document how the backend and frontend integrate with the contracts

1 participant