diff --git a/docs/build/advanced-concepts/flix.md b/docs/build/advanced-concepts/flix.md index 086e0fb988..67e7a2075a 100644 --- a/docs/build/advanced-concepts/flix.md +++ b/docs/build/advanced-concepts/flix.md @@ -8,18 +8,49 @@ Flow Interaction Templates is a standard for how contract developers, wallets, u Interaction Templates provide a way to use and reuse existing scripts and transactions, as well as to provide more metadata such as a human-readable title and description of what the transaction or script will do, which can be used by the developer as well as the user of the application. -By using FLIX transactions and scripts, develoeprs don’t have to write their own for common operations! +By using FLIX transactions and scripts, developers don’t have to write their own for common operations! Read more about the design and purpose of FLIX in the [FLIP](https://github.com/onflow/flips/blob/main/application/20220503-interaction-templates.md) ## Using FLIX -Flow makes FLIX available through an API available at flix.flow.com. Other community run APIs are available, such as flix.ecdao.org. +Flow makes FLIX available through an API available at flix.flow.com. You can query a FLIX API to get an Interaction Template. An example query looks like: https://flix.flow.com/v1/templates?name=transfer-flow You can read more about how to query a FLIX API in the documentation available here: [https://github.com/onflow/flow-interaction-template-service](https://github.com/onflow/flow-interaction-template-service) +:::info + +The FLIX working group is currently working on a protocol to publish FLIX templates on-chain. + +::: + +### Example + +How to integrate FLIX across different developer teams? For this example there are two github repositories. + - (smart contracts) [https://github.com/onflow/hello-world-flix](https://github.com/onflow/hello-world-flix) + - (web development) [https://github.com/onflow/hello-world-web](https://github.com/onflow/hello-world-web) + +The Smart contract developer creates FLIX templates and makes them available in github, these can be versioned. Example is `v0.1.0` release, the templates are available for a specific version. In this example the templates are located at: + - https://github.com/onflow/hello-world-flix/blob/v0.1.0/cadence/templates/ReadHelloWorld.template.json + - https://github.com/onflow/hello-world-flix/blob/v0.1.0/cadence/templates/UpdateHelloWorld.template.json + +Developers can use FLIX templates from the smart contract github to interact with their smart contracts. They simply need the FLIX template URLs to create binding files (TypeScript or JavaScript). One major benefit is the web developers don't need to learn Cadence or copy Cadence to their repository in order to integrate with existing smart contracts. + +TypeScript code generated from templates: +- https://github.com/onflow/hello-world-web/blob/main/app/cadence/readHelloWorld.ts +- https://github.com/onflow/hello-world-web/blob/main/app/cadence/updateHelloWorld.ts + +:::warning + +manually added "@ts-ignore" in generated file because of linting error. 'template' property is typed as "object" when it should also allow strings (url to flix template file). There is current a dev effort that will fix this linting issue. + +::: + +See the `hello-world-web` [README](https://github.com/onflow/hello-world-web/tree/main) for more information on how to generate and execute FLIX templates here [flow-cli flix](../../tools/flow-cli/flix.md) commands + + ### Clients There are currently two clients that have integrated with FLIX that you can use: @@ -30,4 +61,4 @@ There are currently two clients that have integrated with FLIX that you can use: ## (Advanced) Running a FLIX API -Flow provides an implementation of the Flow interaction template service as an open-source project. If you wish to run your own API like flix.flow.com , you can find the repository here: [https://github.com/onflow/flow-interaction-template-service](https://github.com/onflow/flow-interaction-template-service) +Flow provides an implementation of the Flow interaction template service as an open-source project. If you wish to run your own API, you can find the repository here: [https://github.com/onflow/flow-interaction-template-service](https://github.com/onflow/flow-interaction-template-service) diff --git a/docs/build/basics/transactions.md b/docs/build/basics/transactions.md index 050d560ccf..4b558ec492 100644 --- a/docs/build/basics/transactions.md +++ b/docs/build/basics/transactions.md @@ -40,7 +40,7 @@ transaction(greeting: String) { **Arguments** -Transactions may declare parameters it needs during execution, these must be provided as input arguments when sending a transaction. You can think of them as function arguments. Currently, we provide [arguments in the JSON-Cadence Data Interchange Format](../smart-contracts/cadence-reference/json-cadence-spec.md). Which is a human-readable JSON format. The sample script from above accepts a single `String` argument. +Transactions may declare parameters it needs during execution, these must be provided as input arguments when sending a transaction. You can think of them as function arguments. Currently, we provide [arguments in the JSON-Cadence Data Interchange Format](https://cadencelang.dev/docs/1.0/json-cadence-spec). Which is a human-readable JSON format. The sample script from above accepts a single `String` argument. **Reference Block** diff --git a/docs/build/cadence-migration-guide.md b/docs/build/cadence-migration-guide.md deleted file mode 100644 index b4a0c883bb..0000000000 --- a/docs/build/cadence-migration-guide.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Cadence 1.0 Migration Guide -sidebar_label: Cadence Migration Guide -sidebar_position: 9 ---- - -# Cadence 1.0 Migration Guide - -Coming this year, the network will be upgrading to the Cadence 1.0. This means that all applications will need to prepare and migrate their existing Cadence smart contracts, scripts, and transactions for the update. If you do not update your contracts, your applications will become non-functional after the network upgrade. The specific upgrade date will be announced later. - -We have created several resources to help developers update their applications. Use the following links to start upgrading your contracts and to understand how the network upgrade will affect your application: - -- [Understand the upgrade, the timeline, and how it affects you](https://forum.flow.com/t/cadence-1-0-upgrade-plan/5477) -- [Learn how Cadence will be changing for 1.0](https://forum.flow.com/t/update-on-cadence-1-0/5197) -- [Learn how to update your Flow CLI to test against Cadence 1.0](https://forum.flow.com/t/update-on-cadence-1-0/5197/7) -- [Check out the Cadence language 1.0 docs](https://cadencelang.dev/docs/1.0/) - -## Get Help With Migrating Your Dapp to Cadence 1.0 - -If you have any questions related to Cadence 1.0 migration, or if you need help, please contact the Flow development community on [developer-questions Discord channel](https://discord.com/channels/613813861610684416/621847426201944074). Please use “C1.0 upgrade” at the beginning of the message to help us categorize questions related to Cadence 1.0. - -We will soon start hosting regular "Cadence 1.0 upgrade office hours" events anyone can join to ask questions and get help with their dapp upgrade. These sessions will be scheduled in [Flow Webinars & Events calendar](https://calendar.google.com/calendar/u/0?cid=Y180Nzk3OGY1Y2Q5ZGE2MzZjYWRjNmI4NDczMTAyYjUwOTJjMWE4NjVkZDAxMDU1ODM5M2VjYjdmOWZkMGM5YWQwQGdyb3VwLmNhbGVuZGFyLmdvb2dsZS5jb20) and announced on [flow-events Discord channel](https://discord.com/channels/613813861610684416/1050190147100102787). diff --git a/docs/build/smart-contracts/cadence-reference/_category_.yml b/docs/build/smart-contracts/cadence-reference/_category_.yml deleted file mode 100644 index e50ac98c5b..0000000000 --- a/docs/build/smart-contracts/cadence-reference/_category_.yml +++ /dev/null @@ -1 +0,0 @@ -label: Cadence Reference \ No newline at end of file diff --git a/docs/build/smart-contracts/cadence-reference/json-cadence-spec.md b/docs/build/smart-contracts/cadence-reference/json-cadence-spec.md deleted file mode 100644 index 69541262c6..0000000000 --- a/docs/build/smart-contracts/cadence-reference/json-cadence-spec.md +++ /dev/null @@ -1,871 +0,0 @@ ---- -title: JSON-Cadence Data Interchange Format -sidebar_label: JSON-Cadence format ---- - -# JSON-Cadence Data Interchange Format - -> Version 0.3.1 - -JSON-Cadence is a data interchange format used to represent Cadence values as language-independent JSON objects. - -This format includes less type information than a complete [ABI](https://en.wikipedia.org/wiki/Application_binary_interface), and instead promotes the following tenets: - -- **Human-readability** - JSON-Cadence is easy to read and comprehend, which speeds up development and debugging. -- **Compatibility** - JSON is a common format with built-in support in most high-level programming languages, making it easy to parse on a variety of platforms. -- **Portability** - JSON-Cadence is self-describing and thus can be transported and decoded without accompanying type definitions (i.e. an ABI). - -## Values - ---- - -### Void - -```json -{ - "type": "Void" -} -``` - -#### Example - -```json -{ - "type": "Void" -} -``` - ---- - -### Optional - -```json -{ - "type": "Optional", - "value": null | -} -``` - -#### Example - -```json -// Non-nil - -{ - "type": "Optional", - "value": { - "type": "UInt8", - "value": "123" - } -} - -// Nil - -{ - "type": "Optional", - "value": null -} -``` - ---- - -### Bool - -```json -{ - "type": "Bool", - "value": true | false -} -``` - -#### Example - -```json -{ - "type": "Bool", - "value": true -} -``` - ---- - -### String - -```json -{ - "type": "String", - "value": "..." -} - -``` - -#### Example - -```json -{ - "type": "String", - "value": "Hello, world!" -} -``` - ---- - -### Address - -```json -{ - "type": "Address", - "value": "0x0" // as hex-encoded string with 0x prefix -} -``` - -#### Example - -```json -{ - "type": "Address", - "value": "0x1234" -} -``` - ---- - -### Integers - -`[U]Int`, `[U]Int8`, `[U]Int16`, `[U]Int32`,`[U]Int64`,`[U]Int128`, `[U]Int256`, `Word8`, `Word16`, `Word32`, or `Word64` - -Although JSON supports integer literals up to 64 bits, all integer types are encoded as strings for consistency. - -While the static type is not strictly required for decoding, it is provided to inform client of potential range. - -```json -{ - "type": "", - "value": "" -} -``` - -#### Example - -```json -{ - "type": "UInt8", - "value": "123" -} -``` - ---- - -### Fixed Point Numbers - -`[U]Fix64` - -Although fixed point numbers are implemented as integers, JSON-Cadence uses a decimal string representation for readability. - -```json -{ - "type": "[U]Fix64", - "value": "." -} -``` - -#### Example - -```json -{ - "type": "Fix64", - "value": "12.3" -} -``` - ---- - -### Array - -```json -{ - "type": "Array", - "value": [ - , - - // ... - ] -} -``` - -#### Example - -```json -{ - "type": "Array", - "value": [ - { - "type": "Int16", - "value": "123" - }, - { - "type": "String", - "value": "test" - }, - { - "type": "Bool", - "value": true - } - ] -} -``` - ---- - -### Dictionary - -Dictionaries are encoded as a list of key-value pairs to preserve the deterministic ordering implemented by Cadence. - -```json -{ - "type": "Dictionary", - "value": [ - { - "key": "", - "value": - }, - ... - ] -} -``` - -#### Example - -```json -{ - "type": "Dictionary", - "value": [ - { - "key": { - "type": "UInt8", - "value": "123" - }, - "value": { - "type": "String", - "value": "test" - } - } - ], - // ... -} -``` - ---- - -### Composites (Struct, Resource, Event, Contract, Enum) - -Composite fields are encoded as a list of name-value pairs in the order in which they appear in the composite type declaration. - -```json -{ - "type": "Struct" | "Resource" | "Event" | "Contract" | "Enum", - "value": { - "id": "", - "fields": [ - { - "name": "", - "value": - }, - // ... - ] - } -} -``` - -#### Example - -```json -{ - "type": "Resource", - "value": { - "id": "0x3.GreatContract.GreatNFT", - "fields": [ - { - "name": "power", - "value": {"type": "Int", "value": "1"} - } - ] - } -} -``` - ---- - -### Path - -```json -{ - "type": "Path", - "value": { - "domain": "storage" | "private" | "public", - "identifier": "..." - } -} -``` - -#### Example - -```json -{ - "type": "Path", - "value": { - "domain": "storage", - "identifier": "flowTokenVault" - } -} -``` - ---- - -### Type Value - -```json -{ - "type": "Type", - "value": { - "staticType": - } -} -``` - -#### Example - -```json -{ - "type": "Type", - "value": { - "staticType": { - "kind": "Int", - } - } -} -``` - ---- - -### Capability - -```json -{ - "type": "Capability", - "value": { - "path": , - "address": "0x0", // as hex-encoded string with 0x prefix - "borrowType": , - } -} -``` - -#### Example - -```json -{ - "type": "Capability", - "value": { - "path": { - "type": "Path", - "value": { - "domain": "public", - "identifier": "someInteger" - } - }, - "address": "0x1", - "borrowType": { - "kind": "Int" - } - } -} -``` - ---- - -### Functions - -```json -{ - "type": "Function", - "value": { - "functionType": - } -} -``` - -Function values can only be exported, they cannot be imported. - -#### Example - -```json -{ - "type": "Function", - "value": { - "functionType": { - "kind": "Function", - "typeID": "(():Void)", - "parameters": [], - "return": { - "kind": "Void" - } - } - } -} -``` - ---- - -## Types - -### Simple Types - -These are basic types like `Int`, `String`, or `StoragePath`. - -```json -{ - "kind": "Any" | "AnyStruct" | "AnyResource" | "AnyStructAttachment" | "AnyResourceAttachment" | "Type" | - "Void" | "Never" | "Bool" | "String" | "Character" | - "Bytes" | "Address" | "Number" | "SignedNumber" | - "Integer" | "SignedInteger" | "FixedPoint" | - "SignedFixedPoint" | "Int" | "Int8" | "Int16" | - "Int32" | "Int64" | "Int128" | "Int256" | "UInt" | - "UInt8" | "UInt16" | "UInt32" | "UInt64" | "UInt128" | - "UInt256" | "Word8" | "Word16" | "Word32" | "Word64" | - "Fix64" | "UFix64" | "Path" | "CapabilityPath" | "StoragePath" | - "PublicPath" | "PrivatePath" | "AuthAccount" | "PublicAccount" | - "AuthAccount.Keys" | "PublicAccount.Keys" | "AuthAccount.Contracts" | - "PublicAccount.Contracts" | "DeployedContract" | "AccountKey" | "Block" -} -``` - -#### Example - -```json -{ - "kind": "UInt8" -} -``` - ---- - -### Optional Types - -```json -{ - "kind": "Optional", - "type": -} -``` - -#### Example - -```json -{ - "kind": "Optional", - "type": { - "kind": "String" - } -} -``` - ---- - -### Variable Sized Array Types - -```json -{ - "kind": "VariableSizedArray", - "type": -} -``` - -#### Example - -```json -{ - "kind": "VariableSizedArray", - "type": { - "kind": "String" - } -} -``` - ---- - -### Constant Sized Array Types - -```json -{ - "kind": "ConstantSizedArray", - "type": , - "size": , -} -``` - -#### Example - -```json -{ - "kind": "ConstantSizedArray", - "type": { - "kind": "String" - }, - "size":3 -} -``` - ---- - -### Dictionary Types - -```json -{ - "kind": "Dictionary", - "key": , - "value": -} -``` - -#### Example - -```json -{ - "kind": "Dictionary", - "key": { - "kind": "String" - }, - "value": { - "kind": "UInt16" - }, -} -``` - ---- - -### Composite Types - -```json -{ - "kind": "Struct" | "Resource" | "Event" | "Contract" | "StructInterface" | "ResourceInterface" | "ContractInterface", - "type": "", // this field exists only to keep parity with the enum structure below; the value must be the empty string - "typeID": "", - "initializers": [ - , - - // ... - ], - "fields": [ - , - - // ... - ], -} -``` - -#### Example - -```json -{ - "kind": "Resource", - "type": "", - "typeID": "0x3.GreatContract.GreatNFT", - "initializers":[ - [ - { - "label": "foo", - "id": "bar", - "type": { - "kind": "String" - } - } - ] - ], - "fields": [ - { - "id": "foo", - "type": { - "kind": "String" - } - } - ] -} -``` - ---- - -### Field Types - -```json -{ - "id": "", - "type": -} -``` - -#### Example - -```json -{ - "id": "foo", - "type": { - "kind": "String" - } -} -``` - ---- - -### Parameter Types - -```json -{ - "label": "