diff --git a/code/API_definitions/blockchain-public-address.yaml b/code/API_definitions/blockchain-public-address.yaml index e2eb087..1d291ee 100644 --- a/code/API_definitions/blockchain-public-address.yaml +++ b/code/API_definitions/blockchain-public-address.yaml @@ -111,14 +111,14 @@ paths: value: - id: "90c626ce-5284-4a84-b85e-46e0ee3d0434" blockchainPublicAddress: "0x71C7656EC7ab88b098dafB451B2314C5f6d8932A" - blockchainNetworkId: "evm:1" - currency: - - ETH + blockchainNetworkId: "eip155:1" + assets: + - "eip155:1/slip44:60" - id: "5c179f50-db37-4d23-87e3-6f10c991899f" blockchainPublicAddress: "0x329CdCAAC31c934fe32322b111bE8fBd30b4FFA9" - blockchainNetworkId: "evm:137" - currency: - - WETH + blockchainNetworkId: "eip155:137" + assets: + - "eip155:137/erc20:0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619" "400": $ref: "#/components/responses/Generic400" "401": @@ -266,29 +266,49 @@ components: description: User's Blockchain Public Address to bind to the mobile `phoneNumber` blockchainNetworkId: type: string - pattern: ^[a-zA-Z0-9]+:?[a-zA-Z0-9]+$ + pattern: '^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$' description: |- - Identifier (i.e. name/type) of the blockchain whose address value is provided within `blockchainPublicAddress`. The model proposed aims to provide an extensible way to list/identify every blockchain ecosystems. - Proposed format is: `:`, where: - - - ``: Represents a Layer 1 Blockchain Ecosystem (e.g. ethereum, bitcoin,...) - - ``: Represents subsequents L2 and Testnet Blockchain Ecosystems, whenever they apply (e.g. bitcoin is a monolithic blockchain so as this concept does not apply) - - So far, in the scope of v0.2 of this specification, the following `` values are covered: - - `evm`: Representing a common L1 Layer concept for EVM-based networks. Within this Ecosystem, `` concept is required and matches the value of chainId as per [EVM ChainId](https://chainid.network/). For instance: - - `ethereum` blockchain would be identified by `evm:1` value (i.e. ethereum mainnet). - - `polygon` blockchain would be identified by `evm:137` value (i.e. polygon mainnet). - - `celo` blockchain would be identified by `evm:42220` value (i.e. celo mainnet). - - `aleph zero` blockchain would be identified by `evm:41455` value (i.e. aleph zero evm). - - `bitcoin`: Representing Bitcoin L1 blockchain. No `` concept applies for this L1 Ecosystem - - `solana`: Representing Solana L1 blockchain. No `` concept applies for this L1 Ecosystem - - `cardano`: Representing Cardano L1 blockchain. No `` concept applies for this L1 Ecosystem - currency: + Blockchain identifier strictly following the **[CAIP-2](https://chainagnostic.org/CAIPs/caip-2)** standard. + The identifier is composed of a `namespace` and a `reference`, separated by a colon. + + **Format:** `:` + + - **namespace**: A lowercase alphanumeric identifier (3-8 chars) representing the ecosystem or VM (e.g., `eip155` for EVM, `bip122` for Bitcoin, `polkadot`, `solana`). + - **reference**: A unique string (1-32 chars) identifying the specific chain within that namespace. + + **Standard Mapping Examples:** + - **Ethereum Mainnet**: `eip155:1` + - **Bitcoin Mainnet**: `bip122:000000000019d6689c085ae165831e93` + - **Polygon Mainnet**: `eip155:137` + - **Avalanche C-Chain**: `avax:imji8papUf2EhV3le337w1vgFauqkJg-` + - **Avalanche C-Chain (EIP-155 alias) **: `eip155:43114` + - **Avalanche X-Chain**: `avax:8aDU0Kqh-5d23op-B-r-4YbQFRbsgF9a` (Using custom namespace and genesis-based hash) + - **Moonbeam : `polkadot:fe58ea77779b7abda7da4ec526d14db` + - **Moonbeam (EIP-155 alias): `eip155:1284` + - **Rootstock (Bitcoin Sidechain)**: `eip155:30` + - **ApeChain**: `eip155:33139` + + To ensure interoperability, networks that are EVM-compatible should use the `eip155` namespace with their respective `chainId` as the reference. + assets: type: array - description: List of currencies for the blockchain. Optional field (generally not needed), only indicated when there are business needs to set one or a list on currencies supported. + description: |- + List of supported assets for the blockchain, strictly formatted according to the **[CAIP-19 Asset ID](https://chainagnostic.org/CAIPs/caip-19)** standard. For native assets utilizing the `slip44` namespace, refer to the **[SLIP-44 Registry](https://github.com/satoshilabs/slips/blob/master/slip-0044.md)** for standard coin types. + + This is an optional field, generally only indicated when there are business needs to restrict or specify supported assets. + + **Examples:** + - Native Ethereum (ETH): `eip155:1/slip44:60` + - Polygon USDC (ERC-20): `eip155:137/erc20:0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174` + - Moonbeam (GLMR): `eip155:1284/slip44:1284` + - Moonbeam (Native Token ERC-20 Precompile:GLMR): `eip155:1284/erc20:0x0000000000000000000000000000000000000802` + - Avalanche X-Chain (AVAX): `avax:imji8papUf2EhV3le337w1vgFauqkJg-/asset:FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z` + - Avalanche X-Chain (NFT): `avax:imji8papUf2EhV3le337w1vgFauqkJg-/asset:` + - Avalanche P-Chain (AVAX): `avax:imji8papUf2EhV3le337w1vgFauqkJg-/slip44:9000` + - Avalanche C-Chain (AVAX): `eip155:43114/slip44:9000` minItems: 0 items: type: string + pattern: '^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}\/[-a-z0-9]{3,8}:[-a-zA-Z0-9]{1,64}$' nonce: type: string description: |- @@ -304,9 +324,9 @@ components: example: phoneNumber: "+346789990012" blockchainPublicAddress: "0x71C7656EC7ab88b098dafB451B2314C5f6d8932A" - blockchainNetworkId: "evm:1" - currency: - - ETH + blockchainNetworkId: "eip155:1" + assets: + - "eip155:1/slip44:60" BindBlockchainPublicAddressResponse: type: object description: Bind Blockchain Public Address response @@ -332,27 +352,49 @@ components: description: User's Blockchain Public Address blockchainNetworkId: type: string + pattern: '^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$' description: |- - Identifier (i.e. name/type) of the blockchain whose address value is provided within `blockchainPublicAddress`. The model proposed aims to provide an extensible way to list/identify every blockchain ecosystems. - Proposed format is: `:`, where: - - ``: Represents a Layer 1 Blockchain Ecosystem (e.g. ethereum, bitcoin,...) - - ``: Represents subsequents L2 and Testnet Blockchain Ecosystems, whenever they apply (e.g. bitcoin is a monolithic blockchain so as this concept does not apply) - - So far, in the scope of v0.2 of this specification, the following `` values are covered: - - `evm`: Representing a common L1 Layer concept for EVM-based networks. Within this Ecosystem, `` concept is required and matches the value of chainId as per [EVM ChainId](https://chainid.network/). For instance: - - `ethereum` blockchain would be identified by `evm:1` value (i.e. ethereum mainnet). - - `polygon` blockchain would be identified by `evm:137` value (i.e. polygon mainnet). - - `celo` blockchain would be identified by `evm:42220` value (i.e. celo mainnet). - - `aleph zero` blockchain would be identified by `evm:41455` value (i.e. aleph zero evm). - - `bitcoin`: Representing Bitcoin L1 blockchain. No `` concept applies for this L1 Ecosystem - - `solana`: Representing Solana L1 blockchain. No `` concept applies for this L1 Ecosystem - - `cardano`: Representing Cardano L1 blockchain. No `` concept applies for this L1 Ecosystem - currency: + Blockchain identifier strictly following the **[CAIP-2](https://chainagnostic.org/CAIPs/caip-2)** standard. + The identifier is composed of a `namespace` and a `reference`, separated by a colon. + + **Format:** `:` + + - **namespace**: A lowercase alphanumeric identifier (3-8 chars) representing the ecosystem or VM (e.g., `eip155` for EVM, `bip122` for Bitcoin, `polkadot`, `solana`). + - **reference**: A unique string (1-32 chars) identifying the specific chain within that namespace. + + **Standard Mapping Examples:** + - **Ethereum Mainnet**: `eip155:1` + - **Bitcoin Mainnet**: `bip122:000000000019d6689c085ae165831e93` + - **Polygon Mainnet**: `eip155:137` + - **Avalanche C-Chain**: `avax:imji8papUf2EhV3le337w1vgFauqkJg-` + - **Avalanche C-Chain (EIP-155 alias) **: `eip155:43114` + - **Avalanche X-Chain**: `avax:8aDU0Kqh-5d23op-B-r-4YbQFRbsgF9a` (Using custom namespace and genesis-based hash) + - **Moonbeam : `polkadot:fe58ea77779b7abda7da4ec526d14db` + - **Moonbeam (EIP-155 alias): `eip155:1284` + - **Rootstock (Bitcoin Sidechain)**: `eip155:30` + - **ApeChain**: `eip155:33139` + + To ensure interoperability, networks that are EVM-compatible should use the `eip155` namespace with their respective `chainId` as the reference. + assets: type: array - description: List of currencies for the blockchain. Optional field (generally not needed), only indicated when there are business needs to set one or a list on currencies supported. + description: |- + List of supported assets for the blockchain, strictly formatted according to the **[CAIP-19 Asset ID](https://chainagnostic.org/CAIPs/caip-19)** standard. For native assets utilizing the `slip44` namespace, refer to the **[SLIP-44 Registry](https://github.com/satoshilabs/slips/blob/master/slip-0044.md)** for standard coin types. + + This is an optional field, generally only indicated when there are business needs to restrict or specify supported assets. + + **Examples:** + - Native Ethereum (ETH): `eip155:1/slip44:60` + - Polygon USDC (ERC-20): `eip155:137/erc20:0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174` + - Moonbeam (GLMR): `eip155:1284/slip44:1284` + - Moonbeam (Native Token ERC-20 Precompile:GLMR): `eip155:1284/erc20:0x0000000000000000000000000000000000000802` + - Avalanche X-Chain (AVAX): `avax:imji8papUf2EhV3le337w1vgFauqkJg-/asset:FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z` + - Avalanche X-Chain (NFT): `avax:imji8papUf2EhV3le337w1vgFauqkJg-/asset:` + - Avalanche P-Chain (AVAX): `avax:imji8papUf2EhV3le337w1vgFauqkJg-/slip44:9000` + - Avalanche C-Chain (AVAX): `eip155:43114/slip44:9000` minItems: 0 items: type: string + pattern: '^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}\/[-a-z0-9]{3,8}:[-a-zA-Z0-9]{1,64}$' ErrorInfo: type: object required: @@ -375,8 +417,8 @@ components: Problem with the client request. In addition to regular scenario of INVALID_ARGUMENT, other exceptions may exist. - Indicated blockchainNetworkId is not valid ("code": "BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_BLOCKCHAIN_NETWORK_IDENTIFIER","message": "Indicated blockchainNetworkId is not valid") - - Indicated currency is not valid for the Blockchain ("code": "BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_CURRENCY","message": "Indicated currency is not found") - - Currency indication is required ("code": "BLOCKCHAIN_PUBLIC_ADDRESS.CURRENCY_REQUIRED","message": "One currency is required") + - Indicated asset is not valid for the Blockchain ("code": "BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_ASSET","message": "Indicated asset is not found") + - Asset indication is required ("code": "BLOCKCHAIN_PUBLIC_ADDRESS.ASSET_REQUIRED","message": "One asset is required") - Indicated nonce is not valid ("code": "BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_NONCE","message": "Indicated nonce is not valid") - Indicated signature is not valid ("code": "BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_SIGNATURE","message": "Indicated signature is not valid") - Both nonce and signature are required together to perform enhanced validation ("code": "BLOCKCHAIN_PUBLIC_ADDRESS.BOTH_NONCE_SIGNATURE_REQUIRED","message": "Both nonce and signature are required for enhanced validation") @@ -397,8 +439,8 @@ components: enum: - INVALID_ARGUMENT - BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_BLOCKCHAIN_NETWORK_IDENTIFIER - - BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_CURRENCY - - BLOCKCHAIN_PUBLIC_ADDRESS.CURRENCY_REQUIRED + - BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_ASSET + - BLOCKCHAIN_PUBLIC_ADDRESS.ASSET_REQUIRED - BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_NONCE - BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_SIGNATURE - BLOCKCHAIN_PUBLIC_ADDRESS.BOTH_NONCE_SIGNATURE_REQUIRED @@ -415,18 +457,18 @@ components: status: 400 code: BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_BLOCKCHAIN_NETWORK_IDENTIFIER message: Indicated blockchainNetworkId is not valid - GENERIC_400_INVALID_CURRENCY_FOR_BLOCKCHAIN: - description: Invalid currency + GENERIC_400_INVALID_ASSET_FOR_BLOCKCHAIN: + description: Invalid asset value: status: 400 - code: BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_CURRENCY - message: Indicated currency is not found - GENERIC_400_REQUIRED_CURRENCY_FOR_BLOCKCHAIN: - description: Currency is required + code: BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_ASSET + message: Indicated asset is not found + GENERIC_400_REQUIRED_ASSET_FOR_BLOCKCHAIN: + description: Asset is required value: status: 400 - code: BLOCKCHAIN_PUBLIC_ADDRESS.CURRENCY_REQUIRED - message: One currency is required + code: BLOCKCHAIN_PUBLIC_ADDRESS.ASSET_REQUIRED + message: One asset is required GENERIC_400_INVALID_NONCE: description: Invalid nonce value: diff --git a/code/Test_definitions/blockchain-public-address-bindBlockchainPublicAddress.feature b/code/Test_definitions/blockchain-public-address-bindBlockchainPublicAddress.feature index 1cc1d42..23a7d9d 100644 --- a/code/Test_definitions/blockchain-public-address-bindBlockchainPublicAddress.feature +++ b/code/Test_definitions/blockchain-public-address-bindBlockchainPublicAddress.feature @@ -35,13 +35,13 @@ Feature: CAMARA Blockchain Public Address API, vwip - Operation bindBlockchainPu # The response has to comply with the generic response schema which is part of the spec And the response body complies with the OAS schema at "/components/schemas/BindBlockchainPublicAddressResponse" - @bind_blockchain_public_address_02_generic_success_scenario_with_curreny_information - Scenario: Common validations for any success scenario with currency information provided - # Property "$.currency[*]" is set with a valid value supported in the blockChainNetworkId + @bind_blockchain_public_address_02_generic_success_scenario_with_assets_information + Scenario: Common validations for any success scenario with assets information provided + # Property "$.assets[*]" is set with a valid value supported in the blockchainNetworkId Given the request body property "$.phoneNumber" is set with a valid phone number And the request body property "$.blockchainPublicAddress" is set with a valid value And the request body property "$.blockchainNetworkId" is set with a valid value existing in the environment - And the request body property "$.currency[*]" is set with a valid value supported in the blockChainNetworkId + And the request body property "$.assets[*]" is set with a valid value supported in the blockchainNetworkId And the request body is set to a valid request body When the request "bindBlockchainPublicAddress" is sent Then the response status code is 201 @@ -50,7 +50,7 @@ Feature: CAMARA Blockchain Public Address API, vwip - Operation bindBlockchainPu # The response has to comply with the generic response schema which is part of the spec And the response body complies with the OAS schema at "/components/schemas/BindBlockchainPublicAddressResponse" - @bind_blockchain_public_address_02_generic_success_scenario_with_binding_enforcement + @bind_blockchain_public_address_03_generic_success_scenario_with_binding_enforcement Scenario: Common validations for any success scenario with binding enforcement procedure # Properties "$.nonce" and "$.signature" are set with valid values Given the request body property "$.phoneNumber" is set with a valid phone number @@ -102,7 +102,7 @@ Feature: CAMARA Blockchain Public Address API, vwip - Operation bindBlockchainPu Examples: | input_property | oas_spec_schema | - | $.currency | /components/schemas/BindBlockchainPublicAddressRequest | + | $.assets | /components/schemas/BindBlockchainPublicAddressRequest | @bind_blockchain_public_address_400.04_required_input_properties_missing Scenario Outline: Required input properties are missing @@ -128,23 +128,23 @@ Feature: CAMARA Blockchain Public Address API, vwip - Operation bindBlockchainPu And the response property "$.code" is "BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_BLOCKCHAIN_NETWORK_IDENTIFIER" And the response property "$.message" contains a user friendly text - @bind_blockchain_public_address_400.06_invalid_currency - Scenario: Using a invalid currency value - Given the request body property includes property "$.currency" with a not valid value supported by blockChainNetworkId + @bind_blockchain_public_address_400.06_invalid_assets + Scenario: Using an invalid assets value + Given the request body property includes property "$.assets" with a not valid value supported by blockchainNetworkId When the request "bindBlockchainPublicAddress" is sent Then the response status code is 400 And the response property "$.status" is 400 - And the response property "$.code" is "BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_CURRENCY" + And the response property "$.code" is "BLOCKCHAIN_PUBLIC_ADDRESS.INVALID_ASSETS" And the response property "$.message" contains a user friendly text - @bind_blockchain_public_address_400.07_missing_currency + @bind_blockchain_public_address_400.07_missing_assets # Optional scenario that may not be required by a Telco Operator - Scenario: Missing currency - Given the request body property does not include property "$.currency" + Scenario: Missing assets + Given the request body does not include the property "$.assets" When the request "bindBlockchainPublicAddress" is sent Then the response status code is 400 And the response property "$.status" is 400 - And the response property "$.code" is "BLOCKCHAIN_PUBLIC_ADDRESS.CURRENCY_REQUIRED" + And the response property "$.code" is "BLOCKCHAIN_PUBLIC_ADDRESS.ASSETS_REQUIRED" And the response property "$.message" contains a user friendly text @bind_blockchain_public_address_400.08_invalid_x-correlator diff --git a/documentation/API_documentation/blockchain-public-address-User-Story.md b/documentation/API_documentation/blockchain-public-address-User-Story.md index f347ae8..8b7752d 100644 --- a/documentation/API_documentation/blockchain-public-address-User-Story.md +++ b/documentation/API_documentation/blockchain-public-address-User-Story.md @@ -6,7 +6,7 @@ | ***Summary*** | As an application developer, I want a feature to fetch Telco Operator customers Blockchain Public Addresses in a user-friendly way, using Customers Mobile Subscription (i.e. phoneNumber), as a natural and regular pair for the public address of a blockchain. This way management of Blockchain Public Addresses can be perfomed by means of the phoneNumber, which is a natural concept within the OBs. | | ***Roles, Actors and Scope*** | **Roles:** Customer:User
**Actors:** Application service providers, hyperscalers, application developers.
**Scope:** Obtain Blockchain Public Addresses associated to a given phoneNumber of the Customer | | ***Pre-conditions*** | N/A | -| ***Activities/Steps*** | **Starts when:** The API Consumer makes a GET request to the Blockchain Public Address API to obtain the Blockchain Public Addresses associated to a given phoneNumber (generally such addresses are identified by a DID (Decentralised Identifier, which indeed is a public address of a blockchain), composed of 26-35 alphanumeric characters in length).
**Ends when:** The API Consumer receives GET response with the list of Blockchain Public Addresses associated to the phoneNumber, including this information:
- Blockchain public address name.
- Blockchain public address identifier (DID).
- Blockchain public address identifier binding (for latter management).
- Blockchain public address currency.
Empty response will be received in case no Blockchain Public Address is linked to the phonNumber yet. | +| ***Activities/Steps*** | **Starts when:** The API Consumer makes a GET request to the Blockchain Public Address API to obtain the Blockchain Public Addresses associated to a given phoneNumber (generally such addresses are identified by a DID (Decentralised Identifier, which indeed is a public address of a blockchain), composed of 26-35 alphanumeric characters in length).
**Ends when:** The API Consumer receives GET response with the list of Blockchain Public Addresses associated to the phoneNumber, including this information:
- Blockchain public address name.
- Blockchain public address identifier (DID).
- Blockchain public address identifier binding (for latter management).
- Blockchain public address asset.
Empty response will be received in case no Blockchain Public Address is linked to the phonNumber yet. | | ***Post-conditions*** | N/A | | ***Exceptions*** | Several exceptions might occur during the Blockchain Public Address(es) retrieval linked to a given phoneNumber
- Unauthorized: Not valid credentials (e.g. use of already expired access token).
- Invalid Argument: Not valid phoneNumber.
- Internal: Server Error when fetching information. | | -------- | ------------- |