Make sure all fields in the GraphQL schema are documented (#4358)

## Motivation

The GraphQL definitions are a little bit inconsistent. Here we correct
them.

Fixes #1308 

## Proposal

The following changes are made:
* Precising the role of the `ChainId`. For example, for `openChain`, a
naive user may think that the input `chainId` is going to be the chain
ID.
* Removing the fact that chains are subscribed to epoch changes from the
admin chain. I think this is not useful as it is an implementation
detail.
* Removing notes like "system API", which are not useful.
* Remove "(or activates)" which is unclear to me and probably obsolete.
* I added the EVM-relevant notes that occurred in a few places.

## Test Plan

The CI should take care of the schema update.

## Release Plan

- Nothing to do / These changes follow the usual release cycle.

## Links

None

Author: MathieuDutSik

linera-base/src/data_types.rs

@@ -943,11 +943,11 @@ pub struct ApplicationPermissions {
     #[graphql(default)]
     #[debug(skip_if = Vec::is_empty)]
     pub mandatory_applications: Vec<ApplicationId>,
-    /// These applications are allowed to close the current chain using the system API.
+    /// These applications are allowed to close the current chain.
     #[graphql(default)]
     #[debug(skip_if = Vec::is_empty)]
     pub close_chain: Vec<ApplicationId>,
-    /// These applications are allowed to change the application permissions using the system API.
+    /// These applications are allowed to change the application permissions.
     #[graphql(default)]
     #[debug(skip_if = Vec::is_empty)]
     pub change_application_permissions: Vec<ApplicationId>,
@@ -1162,7 +1162,7 @@ pub enum DecompressionError {
     InvalidCompressedBytecode(#[from] io::Error),
 }
 
-/// A compressed WebAssembly module's bytecode.
+/// A compressed module bytecode (WebAssembly or EVM).
 #[derive(Clone, Debug, Deserialize, Hash, Serialize, WitType, WitStore)]
 #[cfg_attr(with_testing, derive(Eq, PartialEq))]
 pub struct CompressedBytecode {
@@ -1533,7 +1533,7 @@ impl StreamUpdate {
 
 impl BcsHashable<'_> for Event {}
 
-doc_scalar!(Bytecode, "A WebAssembly module's bytecode");
+doc_scalar!(Bytecode, "A module bytecode (WebAssembly or EVM)");
 doc_scalar!(Amount, "A non-negative amount of tokens.");
 doc_scalar!(
     Epoch,

linera-base/src/identifiers.rs

@@ -97,7 +97,7 @@ impl From<CryptoHash> for AccountOwner {
 pub struct Account {
     /// The chain of the account.
     pub chain_id: ChainId,
-    /// The owner of the account, or `None` for the chain balance.
+    /// The owner of the account.
     pub owner: AccountOwner,
 }
 

linera-service-graphql-client/gql/service_schema.graphql

@@ -7,7 +7,7 @@ input Account {
 	"""
 	chainId: ChainId!
 	"""
-	The owner of the account, or `None` for the chain balance.
+	The owner of the account.
 	"""
 	owner: AccountOwner!
 }
@@ -21,7 +21,7 @@ type AccountOutput {
 	"""
 	chainId: ChainId!
 	"""
-	The owner of the account, or `None` for the chain balance.
+	The owner of the account.
 	"""
 	owner: AccountOwner!
 }
@@ -68,11 +68,11 @@ input ApplicationPermissions {
 	"""
 	mandatoryApplications: [ApplicationId!]! = []
 	"""
-	These applications are allowed to close the current chain using the system API.
+	These applications are allowed to close the current chain.
 	"""
 	closeChain: [ApplicationId!]! = []
 	"""
-	These applications are allowed to change the application permissions using the system API.
+	These applications are allowed to change the application permissions.
 	"""
 	changeApplicationPermissions: [ApplicationId!]! = []
 	"""
@@ -251,7 +251,7 @@ type BundleInInbox {
 }
 
 """
-A WebAssembly module's bytecode
+A module bytecode (WebAssembly or EVM)
 """
 scalar Bytecode
 
@@ -778,36 +778,119 @@ type MutationRoot {
 	"""
 	Processes the inbox and returns the lists of certificate hashes that were created, if any.
 	"""
-	processInbox(chainId: ChainId!): [CryptoHash!]!
+	processInbox(
+		"""
+		The chain whose inbox is being processed.
+		"""
+		chainId: ChainId!
+	): [CryptoHash!]!
 	"""
 	Retries the pending block that was unsuccessfully proposed earlier.
 	"""
-	retryPendingBlock(chainId: ChainId!): CryptoHash
+	retryPendingBlock(
+		"""
+		The chain on whose block is being retried.
+		"""
+		chainId: ChainId!
+	): CryptoHash
 	"""
 	Transfers `amount` units of value from the given owner's account to the recipient.
 	If no owner is given, try to take the units out of the chain account.
 	"""
-	transfer(chainId: ChainId!, owner: AccountOwner!, recipient: Account!, amount: Amount!): CryptoHash!
+	transfer(
+		"""
+		The chain which native tokens are being transferred from.
+		"""
+		chainId: ChainId!,
+		"""
+		The account being debited on the chain.
+		"""
+		owner: AccountOwner!,
+		"""
+		The recipient of the transfer.
+		"""
+		recipient: Account!,
+		"""
+		The amount being transferred.
+		"""
+		amount: Amount!
+	): CryptoHash!
 	"""
 	Claims `amount` units of value from the given owner's account in the remote
 	`target` chain. Depending on its configuration, the `target` chain may refuse to
 	process the message.
 	"""
-	claim(chainId: ChainId!, owner: AccountOwner!, targetId: ChainId!, recipient: Account!, amount: Amount!): CryptoHash!
+	claim(
+		"""
+		The chain for whom owner is one of the owner.
+		"""
+		chainId: ChainId!,
+		"""
+		The owner of chain targetId being debited.
+		"""
+		owner: AccountOwner!,
+		"""
+		The chain whose owner is being debited.
+		"""
+		targetId: ChainId!,
+		"""
+		The recipient of the transfer.
+		"""
+		recipient: Account!,
+		"""
+		The amount being transferred.
+		"""
+		amount: Amount!
+	): CryptoHash!
 	"""
 	Test if a data blob is readable from a transaction in the current chain.
 	"""
 	readDataBlob(chainId: ChainId!, hash: CryptoHash!): CryptoHash!
 	"""
-	Creates (or activates) a new chain with the given owner.
-	This will automatically subscribe to the future committees created by `admin_id`.
+	Creates a new single-owner chain.
 	"""
-	openChain(chainId: ChainId!, owner: AccountOwner!, balance: Amount): ChainId!
+	openChain(
+		"""
+		The chain paying for the creation of the new chain.
+		"""
+		chainId: ChainId!,
+		"""
+		The owner of the new chain.
+		"""
+		owner: AccountOwner!,
+		"""
+		The balance of the chain being created. Zero if `None`.
+		"""
+		balance: Amount
+	): ChainId!
 	"""
-	Creates (or activates) a new chain by installing the given authentication keys.
-	This will automatically subscribe to the future committees created by `admin_id`.
+	Creates a new multi-owner chain.
 	"""
-	openMultiOwnerChain(		chainId: ChainId!,		applicationPermissions: ApplicationPermissions,		owners: [AccountOwner!]!,		weights: [Int!],		multiLeaderRounds: Int,		balance: Amount,
+	openMultiOwnerChain(
+		"""
+		The chain paying for the creation of the new chain.
+		"""
+		chainId: ChainId!,
+		"""
+		Permissions for applications on the new chain
+		"""
+		applicationPermissions: ApplicationPermissions,
+		"""
+		The owners of the chain
+		"""
+		owners: [AccountOwner!]!,
+		"""
+		The weights of the owners
+		"""
+		weights: [Int!],
+		"""
+		The number of multi-leader rounds
+		"""
+		multiLeaderRounds: Int,
+		"""
+		The balance of the chain. Zero if `None`
+		"""
+		balance: Amount,
 		"""
 		The duration of the fast round, in milliseconds; default: no timeout
 		"""
@@ -826,17 +909,51 @@ type MutationRoot {
 		fallbackDurationMs: Int! = 86400000
 	): ChainId!
 	"""
-	Closes the chain. Returns `None` if it was already closed.
+	Closes the chain. Returns the new block hash if successful or `None` if it was already closed.
 	"""
-	closeChain(chainId: ChainId!): CryptoHash
+	closeChain(
+		"""
+		The chain being closed.
+		"""
+		chainId: ChainId!
+	): CryptoHash
 	"""
-	Changes the authentication key of the chain.
+	Changes the chain to a single-owner chain
 	"""
-	changeOwner(chainId: ChainId!, newOwner: AccountOwner!): CryptoHash!
+	changeOwner(
+		"""
+		The chain whose ownership changes
+		"""
+		chainId: ChainId!,
+		"""
+		The new single owner of the chain
+		"""
+		newOwner: AccountOwner!
+	): CryptoHash!
 	"""
-	Changes the authentication key of the chain.
+	Changes the ownership of the chain
 	"""
-	changeMultipleOwners(		chainId: ChainId!,		newOwners: [AccountOwner!]!,		newWeights: [Int!]!,		multiLeaderRounds: Int!,		openMultiLeaderRounds: Boolean!,
+	changeMultipleOwners(
+		"""
+		The chain whose ownership changes
+		"""
+		chainId: ChainId!,
+		"""
+		The new list of owners of the chain
+		"""
+		newOwners: [AccountOwner!]!,
+		"""
+		The new list of weights of the owners
+		"""
+		newWeights: [Int!]!,
+		"""
+		The multi-leader round of the chain
+		"""
+		multiLeaderRounds: Int!,
+		"""
+		Whether multi-leader rounds are unrestricted, that is not limited to chain owners.
+		"""
+		openMultiLeaderRounds: Boolean!,
 		"""
 		The duration of the fast round, in milliseconds; default: no timeout
 		"""
@@ -857,7 +974,38 @@ type MutationRoot {
 	"""
 	Changes the application permissions configuration on this chain.
 	"""
-	changeApplicationPermissions(chainId: ChainId!, closeChain: [ApplicationId!]!, executeOperations: [ApplicationId!], mandatoryApplications: [ApplicationId!]!, changeApplicationPermissions: [ApplicationId!]!, callServiceAsOracle: [ApplicationId!], makeHttpRequests: [ApplicationId!]): CryptoHash!
+	changeApplicationPermissions(
+		"""
+		The chain whose permissions are being changed
+		"""
+		chainId: ChainId!,
+		"""
+		These applications are allowed to close the current chain.
+		"""
+		closeChain: [ApplicationId!]!,
+		"""
+		If this is `None`, all system operations and application operations are allowed.
+		If it is `Some`, only operations from the specified applications are allowed,
+		and no system operations.
+		"""
+		executeOperations: [ApplicationId!],
+		"""
+		At least one operation or incoming message from each of these applications must occur in every block.
+		"""
+		mandatoryApplications: [ApplicationId!]!,
+		"""
+		These applications are allowed to change the application permissions.
+		"""
+		changeApplicationPermissions: [ApplicationId!]!,
+		"""
+		These applications are allowed to perform calls to services as oracles.
+		"""
+		callServiceAsOracle: [ApplicationId!],
+		"""
+		These applications are allowed to perform HTTP requests.
+		"""
+		makeHttpRequests: [ApplicationId!]
+	): CryptoHash!
 	"""
 	(admin chain only) Registers a new committee. This will notify the subscribers of
 	the admin chain so that they can migrate to the new epoch (by accepting the
@@ -873,15 +1021,62 @@ type MutationRoot {
 	"""
 	Publishes a new application module.
 	"""
-	publishModule(chainId: ChainId!, contract: Bytecode!, service: Bytecode!, vmRuntime: VmRuntime!): ModuleId!
+	publishModule(
+		"""
+		The chain publishing the module
+		"""
+		chainId: ChainId!,
+		"""
+		The bytecode of the contract code
+		"""
+		contract: Bytecode!,
+		"""
+		The bytecode of the service code (only relevant for WebAssembly)
+		"""
+		service: Bytecode!,
+		"""
+		The virtual machine being used (either Wasm or Evm)
+		"""
+		vmRuntime: VmRuntime!
+	): ModuleId!
 	"""
 	Publishes a new data blob.
 	"""
-	publishDataBlob(chainId: ChainId!, bytes: [Int!]!): CryptoHash!
+	publishDataBlob(
+		"""
+		The chain paying for the blob publication
+		"""
+		chainId: ChainId!,
+		"""
+		The content of the data blob being created
+		"""
+		bytes: [Int!]!
+	): CryptoHash!
 	"""
 	Creates a new application.
 	"""
-	createApplication(chainId: ChainId!, moduleId: ModuleId!, parameters: String!, instantiationArgument: String!, requiredApplicationIds: [ApplicationId!]!): ApplicationId!
+	createApplication(
+		"""
+		The chain paying for the creation of the application
+		"""
+		chainId: ChainId!,
+		"""
+		The module ID of the application being created
+		"""
+		moduleId: ModuleId!,
+		"""
+		The JSON serialization of the parameters of the application
+		"""
+		parameters: String!,
+		"""
+		The JSON serialization of the instantiation argument of the application
+		"""
+		instantiationArgument: String!,
+		"""
+		The dependencies of the application being created
+		"""
+		requiredApplicationIds: [ApplicationId!]!
+	): ApplicationId!
 }
 
 """