> For the complete documentation index, see [llms.txt](https://docs.creditcoin.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.creditcoin.org/creditcoin-usc/usc-design-diagrams.md). # USC Design Diagrams 1. Readability Sequence Diagram (See [Readability section](/creditcoin-usc/readability.md) for more details) {% @plantuml/diagram content=" @startuml CC3 !pragma teoz true Actor Claimer participant "Client Side CC3 Library\n (glorified web3 wrapper)" as Client box CC3 #lightblue participant Node database "On-chain storage" as Onchain box EVM #skyblue participant "Prover SC\n \[\[ link]]" as ProverSC end box box Proof-verifier #skyBlue participant "Proof-verifier\n precompile\n \[\[ link]]" as ProofVerifier end box end box participant "Attestors" as Attest database "Ethereum Data" as Eth participant Prover database ProverDb group #lightgrey Attestation Process Attest -> Attest: \[\[file://./Attestation.plantuml Attestation]] end Attest -> Node: Attestation/Checkpoint generated Node -> Prover: Notify about attestation/checkpoint Prover -> ProverDb: Cache attestation/checkpoint skinparam responseMessageBelowArrow true Claimer -> Client: Record ERC20 tx\n tx hash (String/Hash) note left Claimer wants to record on CC3 that they sent ERC20 transfer on ethereum. They provide the Eth transaction hash, together with the block number. end note Client -> Eth: Fetch block containing tx Eth -> Client: Get back the block and tx data Client -> Client: Location of tx in ethereum block Client -> ProverSC: Submit signed transaction with query information\ntx\_hash, chain\_id, block\_num, layout segments ProverSC -> ProverSC: Store query ProverSC <--> Prover: Query submitted event Prover -> Eth: Fetch queried block info Prover -> ProverDb: Fetch relevant checkpint/attestation info Prover -> Prover: Check query for continuity ref over Prover, Prover: \[\[file://./ContinuityProof.plantuml Continuity Proof]] Prover -> Prover: Check query for inclusion ref over Prover, Prover: \[\[file://./InclusionProof.plantuml Inclusion Proof]] Prover -> ProverSC: Submit query proof ProverSC -> ProofVerifier: Verify query proof ProofVerifier -> ProverSC: Return verification result ProverSC -> ProverSC: Store query proof results ProverSC -> Client: Return query proof results Client -> Claimer: Return requested proof results @enduml" %} 2. Continuity Proof Diagram (See [Continuity Proving Doc](/creditcoin-usc/readability/step-1-attestation/continuity-proving-for-attestation.md) for more details) {% @plantuml/diagram content=" @startuml continuity-proof title Continuity Proof for Attestation\nBridging the gap between two sparse attestations on a source chain skinparam shadowing false skinparam roundcorner 8 skinparam defaultTextAlignment center skinparam ArrowColor #444444 skinparam rectangle { BorderColor #444444 } ' ---- Anchors: the sparse, on-chain finalized attestations / checkpoints ---- rectangle "Last finalized attestation\n(or checkpoint)\n\nblock N\ndigest = D(N)" as ANCHOR\_L #D5E8D4 rectangle "New attestation\n\nblock N+k\nprev\_digest = D(N+k-1)\ndigest = D(N+k)" as ANCHOR\_R #D5E8D4 ' ---- The continuity proof: only merkle roots are transmitted ---- package "Continuity Proof (lowerEndpointDigest, roots\[])" #EEF5FF { rectangle "block N+1\nroot r1\n=> D(N+1)" as B1 #FFF2CC rectangle "block N+2\nroot r2\n=> D(N+2)" as B2 #FFF2CC rectangle " ... \nroots\[i]" as BDOTS #FFF2CC rectangle "block N+k-1\nroot r(k-1)\n=> D(N+k-1)" as BK #FFF2CC } ' ---- The digest hash-chain: each digest binds the previous one ---- ANCHOR\_L -right-> B1 : lowerEndpointDigest = D(N) B1 -right-> B2 : prev = D(N+1) B2 -right-> BDOTS : prev = D(N+2) BDOTS -right-> BK : prev = D(N+k-2) BK -right-> ANCHOR\_R : reconstructed D(N+k-1)\nmust equal prev\_digest note bottom of B2 Digest chain (computed on-chain, roots are NOT trusted): **D(i) = keccak256( blockNumber\_i || merkleRoot\_i || D(i-1) )** Changing any block/root breaks every later digest. end note note bottom of ANCHOR\_L Attestations are produced sparsely (e.g. every 10 or 100 blocks) to save cost & bandwidth. The proof fills the gap. end note note bottom of ANCHOR\_R On-chain verification: 1. tail's prev\_digest (= lowerEndpointDigest) points to a known finalized attestation / checkpoint at block N 2. reconstruct the whole chain from roots 3. final digest D(N+k-1) == new attestation prev\_digest Honest attestors converge on the same final digest; bogus blocks yield a different digest and fail quorum. end note @enduml " %} 3. Transaction Proof Payload Diagram (See [Transaction Proving Section](/creditcoin-usc/readability/step-2-transaction-proving.md) for more details) {% @plantuml/diagram content=" @startuml event-proof-package-overview title Event Proof Package — end-to-end\nProving a source-chain transaction/event to a Universal Smart Contract (USC) skinparam shadowing false skinparam roundcorner 8 skinparam defaultTextAlignment center skinparam ArrowColor #444444 skinparam rectangle { BorderColor #444444 } skinparam package { BorderColor #6C8EBF BackgroundColor #EEF5FF } ' ---- Source chain ---- rectangle "Source chain (e.g. Ethereum)\n\nblock matures at height H\ncontains the target tx & receipt\n(emits event such as: TokensBurnedForBridging)" as SRC #FFF2CC ' ---- Off-chain proof builder ---- rectangle "Off-chain Proof Builder\n(proof-gen-api / usc-sdk)\n\nQuery requesting proof: (chainKey, height H, txIndex)" as BUILDER #DAE8FC ' ---- The proof package ---- package "Event Proof Package (submitted to the USC)" as PKG { rectangle "**encodedTransaction**\nABI(txType, chunks\[])\ntx fields + receipt fields\n(status, logs, logsBloom)" as ENC #FFE6CC rectangle "**MerkleProof**\nroot + siblings\[]\n=> proves tx is IN the block" as MP #D5E8D4 rectangle "**ContinuityProof**\nlowerEndpointDigest + roots\[]\n=> proves block is in attested chain" as CP #D5E8D4 } ' ---- USC + precompile ---- rectangle "Universal Smart Contract (USC)\non Creditcoin" as USC #E1D5E7 rectangle "Native Query Verifier precompile\n(0x…0FD2 / BlockProver)\n\nverify(chainKey, H, encodedTx,\n merkleProof, continuityProof)" as PC #E1D5E7 rectangle "On-chain Attestations / Checkpoints\n(pallet-attestation storage)" as ATT #D5E8D4 SRC -down-> BUILDER : fetch block, tx, receipt,\ncompute roots & digests BUILDER -down-> PKG : build 3-part package PKG -down-> USC : dApp call with proof package USC -right-> PC : forward proofs PC -up-> ATT : final digest must match\nan attestation/checkpoint PC -down-> USC : returns true (or reverts) note bottom of USC On success the USC **decodes encodedTransaction** and acts on it: reads receipt **status** (1 = success) and scans **logs** for the event (e.g. TokensBurnedForBridging(burnedFrom, amount)), then runs its business logic (e.g. mint bridged tokens). See: merkle-proof-inclusion, proof-verification-pipeline, encoded-tx-rx-decoding. end note @enduml" %} 4. Writability Sequence Diagram
5. Writability With Acknowledgement (Acknowledgement part of flow uses readability)
6. Bridging tokens from External Chain A to External Chain B using the Attestcoin Protocol \ Simplified path:\ 1\. Readability read from Chain A -> Universal Smart Contract on Creditcoin\ 2\. USC sends writability message -> Chain B receives\ 3\. Readability carries message acknowledgement from Chain B back to USC on Creditcoin {% @plantuml/diagram content=" @startuml bridge-with-readability title Bridge with Readability\nA proven burn on Chain A (READABILITY) triggers a mint on Chain B (WRITABILITY) autonumber skinparam shadowing false skinparam sequenceMessageAlign center skinparam ParticipantPadding 12 skinparam BoxPadding 12 skinparam maxMessageSize 220 box "Source Chain A (origin)" #FFF7E6 actor "User" as U participant "Bridge dApp" as BD participant "TokenA contract" as TA end box box "Creditcoin — Readability\n(attestation + transaction proving)" #EEF5FF participant "Readability Attestors\n(block attestation +\ncontinuity proofs)" as RATT participant "Proof Builder (off-chain)" as PB participant "Creditcoin Chain\n+ NativeQueryVerifier\nprecompile" as CC participant "USC Bridge contract" as USC end box box "Creditcoin — Writability" #F3E6FF participant "Relayer Contract\n+ Quotation System" as RC participant "Outbox\n(one per source chain)" as OUT participant "Message Attestors\n+ Voting Layer" as MATT end box box "Relay" #F0F0F0 participant "Message Relayer" as REL end box box "Source Chain B (destination)" #E6FFE6 participant "Inbox contract" as INB participant "TokenB contract\n(target)" as TB end box \== 1) Burn on the origin chain (Chain A) == U -> BD : request bridge(amount, toChainB, recipient) BD -> TA : bridge(amount, toChainB, recipient) TA -> TA : burn(amount)\n**emit TokensBurnedForBridging(burnedFrom, amount)** note over TA: tx & receipt land in a Chain A block @ height H \== 2) READABILITY — attest & prove the burn to the USC == BD -> CC : wait for attestation of block H on Creditcoin RATT -> RATT : attest Chain A blocks,\nbuild continuity proofs,\nreach consensus RATT -> CC : submit attestation (stored on Creditcoin) note over CC: after sumbissions, block with\nheight H is attested on Creditcoin CC -> BD : block H attested on Creditcoin BD -> PB : request proof package for tx at height H PB -> CC : read attested source-chain state PB -> PB : build **proof package**\n{ encodedTx/rx, MerkleProof, ContinuityProof } PB -> BD : return **proof package**\n{ encodedTx/rx, MerkleProof, ContinuityProof } BD -> USC : submit proof package (chainKey=A, height H, txIndex) USC -> USC : verify(): Merkle inclusion +\ncontinuity chain -> attestation/checkpoint USC -> USC : decode receipt: require status==1,\nmatch log TokensBurnedForBridging\n-> (burnedFrom, amount) note over RATT, USC #D5E8D4: The burn on Chain A is now cryptographically proven on Creditcoin \== 3) WRITABILITY — the verified burn triggers a cross-chain message == BD -> RC : request quote (deliver mint to Chain B) RC -> BD : signed quote (gas + fees) BD -> OUT : publishMessage(payload = mint `amount` to `recipient` on B)\n+ pay quoted fee OUT -> BD : **emit MessagePublished(msgId, payload)** BD -> U : report bridge completion on Chain A\n\*\*\[bridge complete]\*\* \== 4) Message attestation & voting == MATT -> OUT : observe MessagePublished MATT -> MATT : sign + vote + gossip over p2p MATT -> MATT : threshold reached\n**emit MessageReady(msgId)** \== 5) Relay & deliver on the destination chain (Chain B) == REL -> MATT : pick up ready message + attestor votes REL -> INB : deliver(msgId, payload, votes/signatures) INB -> INB : validate attestor votes,\ndecode payload INB -> TB : mint / release `amount` to `recipient` TB -> U : recipient credited on Chain B \[bridge complete] \== 6) (optional) Acknowledgement — READABILITY used again == INB -> INB : **emit MessageDelivered(msgId)** note over REL, USC #FFF2CC Relayer waits for Chain B finality, then submits a query proof of MessageDelivered (same readability path: Merkle + continuity) to the Outbox's Validator. On valid proof the Outbox emits **MessageAcknowledged(msgId)**, which the dApp reports back to the User. end note OUT -> BD : emit MessageAcknowledged(msgId) BD -> U : report bridge completion with acknowledgement @enduml" %}