diff --git a/public/a2a-extensions/concordium-badge/v1/index.html b/public/a2a-extensions/concordium-badge/v1/index.html new file mode 100644 index 0000000000..7c793b851b --- /dev/null +++ b/public/a2a-extensions/concordium-badge/v1/index.html @@ -0,0 +1,31 @@ + + + + + +Verified by Concordium badge — A2A extension v1 + + + +

Verified by Concordium badge — A2A extension, version 1

+

Extension URI (identifier): https://docs.concordium.com/a2a-extensions/concordium-badge/v1

+

This URI identifies version 1 of the Verified by Concordium badge extension for A2A Agent Cards. +An agent declares the extension in capabilities.extensions; the extension's +params object carries the agent's on-chain identity in a CIS-8004 Agent Registry +on the Concordium blockchain.

+

params schema (v1)

+
{
+  "tokenAddress":  string  — the badge, a CAIP-19 cis-2 asset identifier (required)
+  "owner":         object  — { "account": string — CAIP-10 account of the agent owner } (required)
+  "contracts":     object  — { "cis8004": string, "cis8": string } — CAIP-10 contract addresses (required)
+  "verify":        string  — human-readable summary of the verification procedure (required)
+  "verification":  object  — { "service", "verifyUrl", "mcp", "docs" } — resolver hints (optional)
+}
+

Verification is trustless: parse tokenAddress, query the CIS-8004 registry's +agent_of for the token, require status = Active, and require that the +SHA-256 hash of the agent's anchored card equals the on-chain metadata_hash.

+

Breaking changes to this schema will be published under a new URI (/v2); this +document and the v1 schema are stable.

+

Full specification: Verified by Concordium badge

+ + diff --git a/public/llms.txt b/public/llms.txt index c48e4b8755..1dffc02f7f 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -54,6 +54,7 @@ Technical specifications, APIs, tools, and release notes. - [CCDScan](https://docs.concordium.com/en/mainnet/technical-reference/ccd-scan/ccd-scan.html): Blockchain explorer documentation - [Smart contract references](https://docs.concordium.com/en/mainnet/technical-reference/smart-contracts/references-on-chain.html): On-chain references, host functions, and schema format - [Glossary of Concordium terms](https://docs.concordium.com/en/mainnet/technical-reference/glossary.html): Definitions of key terms used across the documentation +- [CAIP identifiers for Concordium](https://docs.concordium.com/en/mainnet/technical-reference/caip-identifiers.html): The ccd namespace profile — CAIP-2 networks, CAIP-10 accounts and contracts (dot-form), CAIP-19 assets (cis-2, plt, slip44:919) - [Release notes](https://docs.concordium.com/en/mainnet/technical-reference/release-notes.html): Node and tool release history - [Downloads](https://docs.concordium.com/en/mainnet/downloads.html): Wallets, node software, and tools @@ -64,8 +65,8 @@ On-chain identity and discovery for AI agents. - [Use the Agent Registry](https://docs.concordium.com/en/mainnet/how-to/integrations/agent-registry.html): Register an agent, link an Ethereum address, and publish a verifiable Agent Card - [CIS-8004: Agent Registry standard](https://docs.concordium.com/en/mainnet/technical-reference/agent-registry/cis-8004.html): CIS-8004 contract specification — token model, entrypoints, and external references - [CIS-8: External Key Registry standard](https://docs.concordium.com/en/mainnet/technical-reference/agent-registry/cis-8.html): CIS-8 contract specification — cross-chain key bindings and proof schemes -- [Agent Card format](https://docs.concordium.com/en/mainnet/technical-reference/agent-registry/agent-card.html): Agent Card JSON structure, Concordium extension block, and card verification -- [Verified by Concordium badge](https://docs.concordium.com/en/mainnet/technical-reference/agent-registry/concordium-badge.html): Badge string format (token address, CAIP-19), trustless resolution and verification, and embedding guidance +- [Agent Card format](https://docs.concordium.com/en/mainnet/technical-reference/agent-registry/agent-card.html): Combined document valid as both an ERC-8004 registration file and an A2A v1.0 Agent Card, with badge extension and card verification +- [Verified by Concordium badge](https://docs.concordium.com/en/mainnet/technical-reference/agent-registry/concordium-badge.html): Badge string format (token address, CAIP-19), trustless resolution and verification, A2A extension embedding, and ERC-8004 registrations - [MCP service](https://docs.concordium.com/en/mainnet/technical-reference/agent-registry/mcp-service.html): Model Context Protocol server — hosted endpoint, local setup, and all available tools - [Indexer](https://docs.concordium.com/en/mainnet/technical-reference/agent-registry/indexer.html): Event indexer for agent discovery — setup, REST API, and sync state diff --git a/source/mainnet/technical-reference/agent-registry/agent-card.rst b/source/mainnet/technical-reference/agent-registry/agent-card.rst index ff4375ae72..af09163bb9 100644 --- a/source/mainnet/technical-reference/agent-registry/agent-card.rst +++ b/source/mainnet/technical-reference/agent-registry/agent-card.rst @@ -9,11 +9,41 @@ An Agent Card is a JSON document that describes a registered AI agent: its ident Any consumer — another agent, an AI development tool, or a human — can verify a card by fetching ``agent_uri``, computing the SHA-256 hash of the raw response body, and comparing it to the ``metadata_hash`` stored on-chain. The MCP tool ``verify_agent_card`` performs this check automatically. -Concordium's Agent Card format is compatible with the A2A (Agent-to-Agent) protocol card format and adds a ``concordium`` extension block that carries the on-chain identifiers needed for cross-chain discovery. +Concordium's Agent Card is a single **combined document**: it is simultaneously a valid ERC-8004 (Trustless Agents) *agent registration file* and a valid A2A v1.0 *Agent Card*, with the Verified by Concordium badge carried as an A2A extension. One anchored JSON therefore serves ERC-8004 tooling, A2A clients, and Concordium verification at once. This works because the two standards compose cleanly: their shared fields (``name``, ``description``) mean the same thing, and each specification tolerates the other's fields — A2A requires implementations to ignore unrecognized fields, and ERC-8004 permits additional fields beyond its mandatory structure. Top-level fields ================ +Fields drawn from **ERC-8004** (registration file structure): + +.. list-table:: + :header-rows: 1 + :widths: 25 15 60 + + * - Field + - Type + - Description + * - ``type`` + - string + - Identifies the document as an ERC-8004 registration file. Fixed value: ``https://eips.ethereum.org/EIPS/eip-8004#registration-v1``. + * - ``image`` + - URI + - Agent image, for compatibility with ERC-721 applications that render the agent NFT. + * - ``services`` + - array + - Named service endpoints, each ``{name, endpoint, version}`` — e.g. an ``A2A`` entry pointing at the card's public URL and an ``MCP`` entry for the agent's MCP endpoint. The list is open-ended. + * - ``x402Support`` + - boolean + - Whether the agent supports x402 proof-of-payment. + * - ``active`` + - boolean + - Whether the agent is operational. + * - ``registrations`` + - array + - The agent's on-chain registrations. Each entry has a numeric ``agentId`` (the CIS-8004 token id) and ``agentRegistry`` as a :doc:`CAIP-10 contract address <../caip-identifiers>`. An array because one agent may be registered in several registries across chains. + +Fields drawn from **A2A v1.0** (Agent Card structure): + .. list-table:: :header-rows: 1 :widths: 25 15 60 @@ -23,52 +53,36 @@ Top-level fields - Description * - ``name`` - string - - Display name of the agent. Maximum 128 characters. + - Display name of the agent. Shared with ERC-8004. Maximum 128 characters. * - ``description`` - string - - Human-readable description of what the agent does. Maximum 2048 characters. + - Human-readable description of what the agent does. Shared with ERC-8004. Maximum 2048 characters. * - ``version`` - string - Semantic version of the agent (e.g. ``1.0.0``). - * - ``url`` - - URI - - Canonical URL where this card is hosted. Must match the ``agent_uri`` registered on-chain. * - ``provider`` - object (optional) - The organisation that operates the agent. Has ``organization`` (string) and ``url`` (URI) sub-fields. + * - ``supportedInterfaces`` + - array + - Endpoints where the agent's A2A service is reachable, each ``{url, protocolBinding, protocolVersion}``, in preference order. + * - ``capabilities`` + - object + - Declared A2A capabilities (``streaming``, ``pushNotifications``) and the ``extensions`` array carrying the :doc:`Verified by Concordium badge ` extension. + * - ``defaultInputModes`` / ``defaultOutputModes`` + - array + - Default request and response media types, e.g. ``["text/plain"]``. * - ``skills`` - array - Capabilities the agent exposes. Each entry has ``id``, ``name``, ``description``, and ``tags`` (string array). * - ``documentationUrl`` - URI (optional) - Link to extended documentation. - * - ``concordium`` - - object - - Concordium-specific extension block. See below. - -Concordium extension block -========================== -The ``concordium`` object is injected automatically by the MCP tool ``build_agent_card``. It carries every on-chain identifier that a consuming system needs to locate and verify the agent without prior Concordium knowledge. +Verified by Concordium badge extension +====================================== -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Field - - Description - * - ``chain_id`` - - CAIP-2 chain identifier for the network the agent is registered on. For mainnet: ``concordium:mainnet``. - * - ``token_address`` - - Base58Check CIS-2 token address derived from ``(contract_index=10082, subindex=0, token_id)``. Uniquely identifies the agent across Concordium tooling. - * - ``cis8004_contract`` - - JSON object ``{"index": 10082, "subindex": 0}`` — the Agent Registry contract address. - * - ``cis8_contract`` - - JSON object ``{"index": 10081, "subindex": 0}`` — the External Key Registry contract address. - * - ``owner`` - - Base58 Concordium account address of the agent's current owner. - * - ``services`` - - Optional key-value map of named service endpoints. For example, ``{"tippingMcp": "https://..."}`` exposes an MCP endpoint that other agents can call to tip this agent. Keys and values are free-form strings. +The badge — the agent's on-chain identity — is declared in ``capabilities.extensions`` under the extension URI ``https://docs.concordium.com/a2a-extensions/concordium-badge/v1``, with its on-chain coordinates (CAIP-19 token address, CAIP-10 owner and contracts, verification hints) in the extension's ``params``. The :doc:`Verified by Concordium badge ` page is the normative definition of the extension and its fields; the example below shows it in place. The MCP tool ``build_agent_card`` injects the extension, the ``registrations`` entry, and all other Concordium-specific fields automatically. Example card ============ @@ -76,40 +90,62 @@ Example card .. code-block:: json { + "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1", "name": "Market Data Agent", "description": "Fetches and summarises real-time CCD/EUR market data on demand.", - "version": "1.0.0", - "url": "https://agents.example.com/market-data/card.json", - "provider": { - "organization": "Example Labs", - "url": "https://example.com" + "image": "https://agents.example.com/market-data/icon.png", + "version": "2.0.0", + "provider": { "organization": "Example Labs", "url": "https://example.com" }, + "supportedInterfaces": [ + { "url": "https://agents.example.com/market-data/a2a/v1", "protocolBinding": "HTTP+JSON", "protocolVersion": "1.0" } + ], + "capabilities": { + "streaming": false, + "pushNotifications": false, + "extensions": [ + { + "uri": "https://docs.concordium.com/a2a-extensions/concordium-badge/v1", + "description": "Verified by Concordium badge — on-chain agent identity in a CIS-8004 registry", + "required": false, + "params": { + "tokenAddress": "ccd:9dd9ca4d19e9393877d2c44b70f89acb/cis-2:Mf22soLh1NuZYFgBK8iSs", + "owner": { + "account": "ccd:9dd9ca4d19e9393877d2c44b70f89acb:3z9dkoTnLi2HEZvjnmKrMec2Gk2NKcEhdi4PugDWzP4GQtZiFa" + }, + "contracts": { + "cis8004": "ccd:9dd9ca4d19e9393877d2c44b70f89acb:10082.0", + "cis8": "ccd:9dd9ca4d19e9393877d2c44b70f89acb:10081.0" + }, + "verify": "Resolve tokenAddress via CIS-8004 agent_of; confirm owner + status is Active + card SHA-256 equals metadata_hash.", + "verification": { + "service": "Concordium Agent Registry", + "verifyUrl": "https://agent-registry-mcp.concordium.com/v1/badge-check/Mf22soLh1NuZYFgBK8iSs", + "mcp": "https://agent-registry-mcp.concordium.com/mcp", + "docs": "https://docs.concordium.com/en/mainnet/technical-reference/agent-registry/concordium-badge.html" + } + } + } + ] }, + "defaultInputModes": ["text/plain"], + "defaultOutputModes": ["text/plain"], "skills": [ - { - "id": "fetch-price", - "name": "Fetch price", - "description": "Returns the current CCD/EUR mid-market price.", - "tags": ["market", "price", "ccd"] - }, - { - "id": "summarise-day", - "name": "Summarise day", - "description": "Returns a one-paragraph summary of today's CCD price action.", - "tags": ["market", "summary", "ccd"] - } + { "id": "fetch-price", "name": "Fetch price", "description": "Returns the current CCD/EUR mid-market price.", "tags": ["market", "price", "ccd"] }, + { "id": "summarise-day", "name": "Summarise day", "description": "Returns a one-paragraph summary of today's CCD price action.", "tags": ["market", "summary", "ccd"] } + ], + "services": [ + { "name": "A2A", "endpoint": "https://agents.example.com/market-data/.well-known/agent-card.json", "version": "1.0" }, + { "name": "MCP", "endpoint": "https://agents.example.com/market-data/mcp", "version": "2025-06-18" } ], - "concordium": { - "chain_id": "concordium:mainnet", - "token_address": "TKN1A2B3C4...", - "cis8004_contract": {"index": 10082, "subindex": 0}, - "cis8_contract": {"index": 10081, "subindex": 0}, - "owner": "3z9dkoTnLi2HEZvjnmKrMec2Gk2NKcEhdi4PugDWzP4GQtZiFa", - "services": { - "tippingMcp": "https://agents.example.com/market-data/mcp" - } - } + "x402Support": false, + "active": true, + "registrations": [ + { "agentId": 484, "agentRegistry": "ccd:9dd9ca4d19e9393877d2c44b70f89acb:10082.0" } + ] } +Cards published before this specification carry the badge as a top-level ``concordium`` object; see :doc:`Legacy embedding ` on the badge page. Verifiers accept both forms. + Building and hosting a card ============================ diff --git a/source/mainnet/technical-reference/agent-registry/concordium-badge.rst b/source/mainnet/technical-reference/agent-registry/concordium-badge.rst index 5c1451a735..2b6af41c52 100644 --- a/source/mainnet/technical-reference/agent-registry/concordium-badge.rst +++ b/source/mainnet/technical-reference/agent-registry/concordium-badge.rst @@ -69,28 +69,70 @@ A passing check proves that the agent is registered in the Agent Registry, is cu Embed the badge =============== -Agent Card ----------- +Agent Card extension (normative) +-------------------------------- -Add a ``concordium`` block to the :doc:`Agent Card `: +The badge is embedded in the :doc:`Agent Card ` as an **A2A extension**, declared in ``capabilities.extensions`` under the versioned extension URI ``https://docs.concordium.com/a2a-extensions/concordium-badge/v1``: .. code-block:: json - "concordium": { - "tokenAddress": "ccd:9dd9ca4d19e9393877d2c44b70f89acb/cis-2:Mf22soLh1NuZYFgBK8iSs", - "tokenAddressBase58": "Mf22soLh1NuZYFgBK8iSs", - "chain": "ccd:9dd9ca4d19e9393877d2c44b70f89acb", - "owner": { "account": "", "caip10": "ccd:9dd9ca4d…:" }, - "contracts": { "cis8004": "10082,0", "cis8": "10081,0" }, - "verify": "Resolve tokenAddress via CIS-8004 agent_of; confirm owner + status=Active + card SHA-256 == metadata_hash.", - "verification": { - "service": "Concordium Agent Registry", - "verifyUrl": "https://agent-registry-mcp.concordium.com/v1/badge-check/", - "mcp": "https://agent-registry-mcp.concordium.com/mcp", - "docs": "https://docs.concordium.com/en/mainnet/technical-reference/agent-registry/concordium-badge.html" - } + "capabilities": { + "extensions": [ + { + "uri": "https://docs.concordium.com/a2a-extensions/concordium-badge/v1", + "description": "Verified by Concordium badge — on-chain agent identity in a CIS-8004 registry", + "required": false, + "params": { + "tokenAddress": "ccd:9dd9ca4d19e9393877d2c44b70f89acb/cis-2:Mf22soLh1NuZYFgBK8iSs", + "owner": { + "account": "ccd:9dd9ca4d19e9393877d2c44b70f89acb:3z9dkoTnLi2HEZvjnmKrMec2Gk2NKcEhdi4PugDWzP4GQtZiFa" + }, + "contracts": { + "cis8004": "ccd:9dd9ca4d19e9393877d2c44b70f89acb:10082.0", + "cis8": "ccd:9dd9ca4d19e9393877d2c44b70f89acb:10081.0" + }, + "verify": "Resolve tokenAddress via CIS-8004 agent_of; confirm owner + status is Active + card SHA-256 equals metadata_hash.", + "verification": { + "service": "Concordium Agent Registry", + "verifyUrl": "https://agent-registry-mcp.concordium.com/v1/badge-check/Mf22soLh1NuZYFgBK8iSs", + "mcp": "https://agent-registry-mcp.concordium.com/mcp", + "docs": "https://docs.concordium.com/en/mainnet/technical-reference/agent-registry/concordium-badge.html" + } + } + } + ] } +Every on-chain reference in ``params`` is a full :doc:`CAIP identifier <../caip-identifiers>`: ``tokenAddress`` is the badge in CAIP-19 form (the short form is the segment after ``cis-2:``), ``owner.account`` is a CAIP-10 account, and each entry in ``contracts`` is a CAIP-10 contract address, so the network is explicit in every value and no separate ``chain`` field is needed. + +.. note:: + + **Why an extension, not a top-level field.** The A2A specification requires that extensions place their data in the sanctioned extension mechanism — an ``AgentExtension`` entry in ``capabilities.extensions`` with a URI-identified ``params`` object — and prohibits extensions from adding new top-level fields to core data structures. The URI is the extension's identity and version: a consumer locates the badge by matching the URI, and any breaking change to the ``params`` schema mints a new URI (``/v2``), never a change to this one. Do not move this block to the top level of the card. + +ERC-8004 registrations entry +---------------------------- + +For interoperability with ERC-8004 (Trustless Agents) tooling, the agent's anchored registration document also carries an ERC-8004 ``registrations`` entry identifying the agent's on-chain registration: + +.. code-block:: json + + "registrations": [ + { + "agentId": 484, + "agentRegistry": "ccd:9dd9ca4d19e9393877d2c44b70f89acb:10082.0" + } + ] + +``agentId`` is the CIS-8004 token id as a JSON number and ``agentRegistry`` is the registry contract as a CAIP-10 contract address, matching ERC-8004's ``{namespace}:{chainId}:{identityRegistry}`` shape. The field is an array because ERC-8004 allows one agent to hold registrations in several registries — a Concordium entry can sit beside ``eip155:`` entries for a cross-chain agent. Per the current ERC-8004 draft, ``registrations`` belongs in the agent registration file — the document the on-chain ``agent_uri`` resolves to. See the :doc:`Agent Card ` page for the combined document that satisfies both ERC-8004 and A2A at once. + +Legacy embedding +---------------- + +Cards published before this specification carry the badge as a top-level ``concordium`` object instead of the extension above. Such badges remain fully valid — verification never depended on where the block sits in the card — and verifiers should accept both placements. New cards, and existing cards when they are next re-anchored, should use the extension form. + +Verification hints +------------------ + The ``verify`` string names the steps; the optional ``verification`` block names **where to run them** — ``service``, ``verifyUrl``, ``mcp``, and ``docs``. Together they make a badge *self-resolving*: a consumer that has never seen Concordium can verify it from the card alone. The values below are Concordium's official Agent Registry service, shown as an example — the block is **not limited to them**. Any issuer may point these fields at a different service that runs the same checks, and any party may ignore the hints entirely and resolve directly against the contracts in ``contracts``. .. list-table:: @@ -102,7 +144,7 @@ The ``verify`` string names the steps; the optional ``verification`` block names * - ``service`` - Human-readable name of the resolver / registry service. * - ``verifyUrl`` - - REST endpoint keyed on the badge itself (``tokenAddressBase58``) — a single ``GET`` returns the JSON verdict for **this** badge (owner, ``status``, and card-hash match). No MCP client, SDK, or node access required. + - REST endpoint keyed on the badge itself (its short form) — a single ``GET`` returns the JSON verdict for **this** badge (owner, ``status``, and card-hash match). No MCP client, SDK, or node access required. * - ``mcp`` - MCP endpoint for agents that speak the Model Context Protocol; they can call ``verify_agent_card`` / ``agent_by_token_address`` directly. * - ``docs`` @@ -134,7 +176,9 @@ The badge introduces no new standard. It composes: - :doc:`CIS-8004 ` — Agent Registry / agent NFT - CIS-2 — token-address encoding -- CAIP-2 / CAIP-10 / CAIP-19 — portable chain, account, and asset identifiers +- :doc:`CAIP-2 / CAIP-10 / CAIP-19 <../caip-identifiers>` — portable chain, account, and asset identifiers +- A2A extensions — the Agent Card's sanctioned mechanism for vendor data (``capabilities.extensions``) +- ERC-8004 (Trustless Agents) — the ``registrations`` entry linking a card to its on-chain registry - :doc:`CIS-8 ` — external key binding - :doc:`Agent Card ` — the agent's published metadata document diff --git a/source/mainnet/technical-reference/caip-identifiers.rst b/source/mainnet/technical-reference/caip-identifiers.rst new file mode 100644 index 0000000000..224088e1b2 --- /dev/null +++ b/source/mainnet/technical-reference/caip-identifiers.rst @@ -0,0 +1,130 @@ +.. include:: ../variables.rst +.. _caip-identifiers: + +================================ +CAIP identifiers for Concordium +================================ + +Concordium uses Chain Agnostic Improvement Proposal (CAIP) identifiers wherever an on-chain object — a network, an account, a smart contract, or an asset — is referenced from an off-chain document, so that consumers on any chain can parse the reference without Concordium-specific knowledge. The :doc:`Verified by Concordium badge ` and the :doc:`Agent Card ` use these identifiers throughout. + +This page documents the ``ccd`` namespace profile. The namespace and its CAIP-2 profile are registered in the ChainAgnostic namespaces registry; the CAIP-10 and CAIP-19 profiles below are being submitted to the registry and are documented here as the authoritative definition in the meantime. + +CAIP-2 — Networks +================= + +*Registered:* the ``ccd`` CAIP-2 profile is published in the ChainAgnostic namespaces registry. + +Syntax +------ + +A Concordium network is identified by ``ccd:`` followed by the hash of the network's genesis block in hexadecimal encoding, truncated to the first 32 characters. + +Resolution mechanics +-------------------- + +The genesis block hash is obtained from any Concordium node via the gRPC ``GetConsensusInfo`` query (``genesisBlock`` field), or with ``concordium-client raw GetConsensusInfo``, then truncated to the first 32 hexadecimal characters. + +Test cases +---------- + +.. code-block:: text + + # Concordium mainnet + ccd:9dd9ca4d19e9393877d2c44b70f89acb + + # Current Concordium testnet + ccd:4221332d34e1694168c2a0c0b3fd0f27 + +CAIP-10 — Accounts and smart contracts +====================================== + +*Registration with the ChainAgnostic registry pending.* + +Syntax +------ + +**Account address.** A Concordium account is identified by the CAIP-2 network identifier, a colon, and the account's Base58Check address: + +.. code-block:: text + + ccd:: + +**Smart contract address.** A Concordium smart contract is natively addressed by an index and subindex pair, written ````. In CAIP-10 form the comma is substituted with a dot, because the comma is not a valid CAIP-10 character: + +.. code-block:: text + + ccd::. + +Resolution mechanics +-------------------- + +An account identifier resolves by querying the account address on the identified network. A contract identifier ``ccd::1234.0`` resolves to the native contract address ``<1234,0>`` — split the final segment on the dot to recover the index and subindex, both non-negative integers. The two forms are distinguishable without ambiguity: contract references contain a dot and consist only of digits and a dot, while Base58Check account addresses do not. + +Test cases +---------- + +.. code-block:: text + + # Concordium mainnet account + ccd:9dd9ca4d19e9393877d2c44b70f89acb:4FmiTW2L2AccyR9VjzsnpWFSAcohXWf7Vf797i36y526mqiEcp + + # Current Concordium testnet account + ccd:4221332d34e1694168c2a0c0b3fd0f27:3kBx2h5Y2veb4hZgAJWPrr8RyQESKm5TjzF3ti1QQ4VSYLwK1G + + # Concordium mainnet smart contract <1234,0> + ccd:9dd9ca4d19e9393877d2c44b70f89acb:1234.0 + + # Current Concordium testnet smart contract <1234,0> + ccd:4221332d34e1694168c2a0c0b3fd0f27:1234.0 + +CAIP-19 — Assets +================ + +*Registration with the ChainAgnostic registry pending.* + +Syntax +------ + +A Concordium asset is identified by the CAIP-2 network identifier, a slash, an asset namespace, a colon, and an asset reference. Three asset namespaces are defined: + +.. list-table:: + :header-rows: 1 + :widths: 15 35 50 + + * - Namespace + - Reference + - Identifies + * - ``cis-2`` + - Base58Check token address + - A CIS-2 token instance. The token address encodes the contract address and token id in one string. + * - ``plt`` + - Token symbol + - A protocol-level token (PLT), identified by its unique symbol. + * - ``slip44`` + - ``919`` + - CCD itself, per the SLIP-44 registered coin type for Concordium. + +Resolution mechanics +-------------------- + +A ``cis-2`` reference is parsed with the ``@concordium/web-sdk`` helper ``tokenAddressFromBase58`` (inverse: ``tokenAddressToBase58``), yielding the contract address and token id: ``Base58Check( 0x02 ‖ ULEB128(contract_index) ‖ ULEB128(contract_subindex) ‖ token_id_bytes )``. A ``plt`` reference resolves via the protocol-level token registry on the identified network. ``slip44:919`` requires no resolution — it denotes the network's native CCD. + +Test cases +---------- + +.. code-block:: text + + # Concordium mainnet + ccd:9dd9ca4d19e9393877d2c44b70f89acb/cis-2:3rE6rK8FrW1nsQYB + ccd:9dd9ca4d19e9393877d2c44b70f89acb/plt:eGOLD + ccd:9dd9ca4d19e9393877d2c44b70f89acb/slip44:919 + + # Current Concordium testnet + ccd:4221332d34e1694168c2a0c0b3fd0f27/cis-2:9Caati1emwuNgVd3aBFmFEiYhRGPT2ra4u9T7mXn9wtHo2Kd4P278w + ccd:4221332d34e1694168c2a0c0b3fd0f27/plt:EUDemo + ccd:4221332d34e1694168c2a0c0b3fd0f27/slip44:919 + +Usage in the agent stack +======================== + +The :doc:`Verified by Concordium badge ` is a CAIP-19 ``cis-2`` identifier; the badge extension's ``owner`` and ``contracts`` fields are CAIP-10 identifiers; and the ERC-8004 ``registrations`` entry uses the CAIP-10 contract form for ``agentRegistry``. Using full CAIP identifiers everywhere makes each value self-describing — the network is explicit in the string — and lets cross-chain tooling treat ``ccd:`` references exactly like references in any other registered namespace. diff --git a/source/mainnet/technical-reference/index.rst b/source/mainnet/technical-reference/index.rst index 81638c6be5..c8abae0afa 100644 --- a/source/mainnet/technical-reference/index.rst +++ b/source/mainnet/technical-reference/index.rst @@ -61,6 +61,10 @@ Reference documentation for Concordium APIs, SDKs, command-line tools, smart con - :doc:`MCP service ` - :doc:`Indexer ` + **Standards** + + - :doc:`CAIP identifiers ` + **Identity** - :doc:`ID attributes ` @@ -131,6 +135,12 @@ Reference documentation for Concordium APIs, SDKs, command-line tools, smart con MCP service Indexer +.. toctree:: + :caption: Standards + :hidden: + + CAIP identifiers + .. toctree:: :caption: Identity :hidden: