diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 0168cb975..a704766aa 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -12,110 +12,52 @@ jobs: runs-on: ubuntu-latest permissions: contents: write - concurrency: - group: ${{ github.workflow }}-${{ github.ref }} steps: - - # This is a regex from https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string - # It is used in this GitHub action in a couple places to find semver named directories (with a 'v' on the front) - - name: Set SEMVER_REGEX - run: echo "SEMVER_REGEX='^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'" >> $GITHUB_ENV - - - name: Checkout the current commit + - name: Checkout source uses: actions/checkout@v3 with: fetch-depth: 0 - - # If this is a new release, get the previous versions of the docs to build the full list of versions - - name: Checkout the gh-pages branch - if: github.event_name == 'release' - uses: actions/checkout@v3 - with: - ref: gh-pages - path: gh-pages - - - name: Setup Ruby - uses: ruby/setup-ruby@v1 - with: - ruby-version: '3.0' - - name: Install bundler - run: gem install bundler:1.17.2 - - # If this was a merge to main, set the version to "head" - - name: Set version env var to 'head' - if: github.event_name == 'push' - run: echo "DOCS_VERSION=head" >> $GITHUB_ENV - - # If this was a release, set the version number - - name: Set version env var - if: github.event_name == 'release' - run: echo "DOCS_VERSION=${GITHUB_REF##*/}" >> $GITHUB_ENV - - - name: Set version in _config.yml + - name: Setup Docs Deploy run: | - echo "version: ${{ env.DOCS_VERSION }}" >> ./docs/_config.yml - - # Only need to build the full list of versions every time there is a new release - # This uses a regex to determine which existing directories are "versions" and should be listed in the version.json file. - # The output of this command is a version.json file containing a JSON array of all semver released versions of the docs, plus "latest" and "head" - - name: Update version.json list - if: github.event_name == 'release' - run: ls ./gh-pages | grep -E ${{ env.SEMVER_REGEX }} | sed 's/^/"/;s/$/"/' | tr '\n' ',' | sed 's/.$//' | sed 's/^/[/;s/$/]/' | jq '. += ["${{ env.DOCS_VERSION }}"] | sort_by(.) | reverse | . += ["latest", "head"]' > ./docs/assets/js/versions.json - - - name: Install dependencies - working-directory: docs - run: bundle install - - - name: Build doc site version - working-directory: docs - run: bundle exec jekyll build --baseurl /firefly/${{ env.DOCS_VERSION }} - - - name: Check the docs for broken links (root) - if: github.event_name == 'pull_request' - working-directory: docs - run: bundle exec htmlproofer --disable-external --allow-hash-href --allow_missing_href true --swap-urls '^/firefly/:/' --ignore-urls /127.0.0.1/,/localhost/ ./_site - - - name: Check the docs for broken links (version) - if: github.event_name != 'pull_request' - working-directory: docs - run: bundle exec htmlproofer --disable-external --allow-hash-href --allow_missing_href true --swap-urls '^/firefly/${{ env.DOCS_VERSION }}/:/' --ignore-urls /127.0.0.1/,/localhost/ ./_site - - - name: Deploy docs (version) - if: github.event_name == 'push' - uses: peaceiris/actions-gh-pages@v3 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_branch: gh-pages - publish_dir: ./docs/_site - destination_dir: ./${{ env.DOCS_VERSION }} - - ## FINAL STEPS TO COMPLETE IF THIS WAS A NEW RELEASE ## - - - name: Copy new version into version directory - if: github.event_name == 'release' - working-directory: docs - run: mv _site ${{ env.DOCS_VERSION }} - - # This uses a regex from to determine which existing directories are "versions" and should be copied over - - name: Copy existing versions into working directory - if: github.event_name == 'release' - run: ls ./gh-pages | grep -E ${{ env.SEMVER_REGEX }} | xargs -I '{}' mv './gh-pages/{}' ./docs - - - name: Copy existing 'head' directory into working directory - if: github.event_name == 'release' - run: mv ./gh-pages/head ./docs - - - name: Build doc site (latest) - if: github.event_name == 'release' - working-directory: docs - run: bundle exec jekyll build --baseurl /firefly - - - name: Deploy docs (latest) - if: github.event_name == 'release' - uses: peaceiris/actions-gh-pages@v3 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_branch: gh-pages - publish_dir: ./docs/_site + git config --global user.name "GitHub Actions" + git config --global user.email "noreply@github.com" + - name: Check if this is the latest release + run: | + LATEST_TAG=$( + curl -L \ + -H "Accept: application/vnd.github+json" \ + -H "Authorization: Bearer ${{ github.token }}" \ + -H "X-GitHub-Api-Version: 2022-11-28" \ + https://api.github.com/repos/${{ github.repository }}/releases/latest \ + | jq -r '.tag_name' + ) + IS_LATEST=${{ env.LATEST_TAG == github.event.release.tag_name }} + echo This release is: "${{ github.event.release.tag_name }}" + echo The latest release is: "$LATEST_TAG" + echo "IS_LATEST_RELEASE=$IS_LATEST" >> "$GITHUB_ENV" + + - name: Install docs dependencies + working-directory: doc-site + run: pip install -r requirements.txt + + - name: Update doc site for release + if: ${{ github.event_name == 'release' && env.IS_LATEST_RELEASE != 'true' }} + working-directory: doc-site + run: mike deploy ${{ github.event.release.tag_name }} --push + + - name: Update doc site for latest release + if: ${{ github.event_name == 'release' && env.IS_LATEST_RELEASE == 'true' }} + working-directory: doc-site + run: mike deploy ${{ github.event.release.tag_name }} latest --push + + - name: Update doc site for `main` branch + if: ${{ github.event_name == 'push' }} + working-directory: doc-site + run: mike deploy head --push + + - name: Test building the doc site but do not deploy it + if: ${{ github.event_name == 'pull_request' }} + working-directory: doc-site + run: mkdocs build diff --git a/.gitignore b/.gitignore index 9712d21a3..f716852eb 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,4 @@ __debug* containerlogs .vscode/*.log .idea +doc-site/site \ No newline at end of file diff --git a/Makefile b/Makefile index dc8f69c08..bcd40335e 100644 --- a/Makefile +++ b/Makefile @@ -14,7 +14,7 @@ GOGC=30 all: build test go-mod-tidy test: deps lint - $(VGO) test ./internal/... ./pkg/... ./cmd/... ./docs ./ffconfig/... -cover -coverprofile=coverage.txt -covermode=atomic -timeout=30s ${TEST_ARGS} + $(VGO) test ./internal/... ./pkg/... ./cmd/... ./doc-site ./ffconfig/... -cover -coverprofile=coverage.txt -covermode=atomic -timeout=30s ${TEST_ARGS} coverage.html: $(VGO) tool cover -html=coverage.txt coverage: test coverage.html @@ -99,7 +99,7 @@ clean: deps: $(VGO) get reference: - $(VGO) test ./internal/apiserver ./internal/reference ./docs -timeout=10s -tags reference + $(VGO) test ./internal/apiserver ./internal/reference ./doc-site -timeout=10s -tags reference manifest: ./manifestgen.sh docker: @@ -107,4 +107,4 @@ docker: docker-multiarch: ./docker_build.sh --platform linux/amd64,linux/arm64 $(DOCKER_ARGS) docs: .ALWAYS - cd docs && bundle install && bundle exec jekyll build && bundle exec htmlproofer --disable-external --allow-hash-href --allow_missing_href true --swap-urls '^/firefly/:/' --ignore-urls /127.0.0.1/,/localhost/ ./_site + cd doc-site && mkdocs build diff --git a/doc-site/.github/ISSUE_TEMPLATE/bug-report.yml b/doc-site/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 000000000..cc088450c --- /dev/null +++ b/doc-site/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,62 @@ +name: 🐞 Bug +description: File a bug/issue +title: "bug: " +labels: [bug] +body: + - type: markdown + attributes: + value: | + _The more information you share, the faster we can help you._ + Prior to opening the issue, please make sure that you: + - Use English (EN/US) to communicate. + - Search the [open issues](https://github.com/hyperledger-labs/documentation-template/issues) to avoid duplicating the issue. + + - type: textarea + id: problem + attributes: + label: What happened? + description: | + Please provide as much info as possible. Not doing so may result in your bug not being addressed in a timely manner. + If this matter is security related, please disclose it privately via security@hyperledger.org + validations: + required: true + + - type: textarea + id: expected + attributes: + label: What did you expect to happen? + validations: + required: true + + - type: textarea + id: repro + attributes: + label: How can we reproduce it (as minimally and precisely as possible)? + validations: + required: true + + - type: textarea + id: additional + attributes: + label: Anything else we need to know? + + - type: textarea + id: osVersion + attributes: + label: OS version + value: | +
+ + ```console + # On Linux: + $ cat /etc/os-release + # paste output here + $ uname -a + # paste output here + + # On Windows: + C:\> wmic os get Caption, Version, BuildNumber, OSArchitecture + # paste output here + ``` + +
\ No newline at end of file diff --git a/doc-site/.github/ISSUE_TEMPLATE/config.yml b/doc-site/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..be70b645d --- /dev/null +++ b/doc-site/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Support Request + url: https://discord.gg/hyperledger + about: Support request or question relating to Hyperledger Docs \ No newline at end of file diff --git a/doc-site/.github/ISSUE_TEMPLATE/enhancement.yml b/doc-site/.github/ISSUE_TEMPLATE/enhancement.yml new file mode 100644 index 000000000..032af6cc6 --- /dev/null +++ b/doc-site/.github/ISSUE_TEMPLATE/enhancement.yml @@ -0,0 +1,27 @@ +name: Enhancement Tracking Issue +description: Provide supporting details for an enhancement +labels: [enhancement] +body: + - type: markdown + attributes: + value: | + _The more information you share, the faster we can help you._ + Prior to opening the issue, please make sure that you: + - Use English (EN/US) to communicate. + - Search the [open issues](https://github.com/hyperledger-labs/documentation-template/issues) to avoid duplicating the issue. + + - type: textarea + id: enhancement + attributes: + label: What would you like to be added? + description: | + A clear and concise description of what you want to happen. + validations: + required: true + + - type: textarea + id: rationale + attributes: + label: Why is this needed? + validations: + required: true \ No newline at end of file diff --git a/doc-site/.github/ISSUE_TEMPLATE/improve_docs.yml b/doc-site/.github/ISSUE_TEMPLATE/improve_docs.yml new file mode 100644 index 000000000..d33a787d7 --- /dev/null +++ b/doc-site/.github/ISSUE_TEMPLATE/improve_docs.yml @@ -0,0 +1,31 @@ +name: "Documentation Issue" +description: Issues related to documentation. +title: "docs: " +labels: [documentation] +body: + - type: markdown + attributes: + value: | + _The more information you share, the faster we can help you._ + Prior to opening the issue, please make sure that you: + - Use English (EN/US) to communicate. + - Search the [open issues](https://github.com/hyperledger-labs/documentation-template/issues) to avoid duplicating the issue. + + - type: textarea + id: current-state + attributes: + label: Current State + description: Describe the current state of the documentation. + placeholder: | + The documentation for the API in this page (url) is missing ... + validations: + required: true + - type: textarea + id: desired-state + attributes: + label: Desired State + description: Describe the desired state the documentation should be in. + placeholder: | + Add here ... + validations: + required: true \ No newline at end of file diff --git a/doc-site/.github/labels.yml b/doc-site/.github/labels.yml new file mode 100644 index 000000000..f6d3cfce4 --- /dev/null +++ b/doc-site/.github/labels.yml @@ -0,0 +1,36 @@ +- name: bug + description: Something isn't working + color: b60205 +- name: documentation + description: Improvements or additions to documentation + color: 0052cc +- name: duplicate + description: This issue or pull request already exists + color: 9c99a3 +- name: enhancement + description: New feature or request + color: 1dbfcf +- name: good first issue + description: Good for newcomers + color: 8141f0 +- name: help wanted + description: Extra attention is needed + color: 0ac492 +- name: invalid + description: This doesn't seem right + color: e6da05 +- name: needs triage + description: New issue that has not yet been looked at + color: 69a6d1 +- name: question + description: Further information is requested + color: 8a23b0 +- name: wontfix + description: This will not be worked on + color: ccb5ab +- name: stale + description: no commits in last 30 days + color: 382c0d +- name: awaiting response + description: Waiting for user response + color: d1821b \ No newline at end of file diff --git a/doc-site/.github/pull_request_template.md b/doc-site/.github/pull_request_template.md new file mode 100644 index 000000000..8cb3505fe --- /dev/null +++ b/doc-site/.github/pull_request_template.md @@ -0,0 +1,45 @@ + + +## Proposed changes + +Please include a summary of the changes here and why we need those changes. And also let us know which issue is fixed. + +Fixes # + +
+ +## Types of changes + + + + + +- [ ] Bug fix +- [ ] New feature added +- [ ] Documentation Update + +
+ +## Please make sure to follow these points + + + + + +- [ ] I have read the contributing guidelines. +- [ ] I have performed a self-review of my own code or work. +- [ ] I have commented my code, particularly in hard-to-understand areas. +- [ ] My changes generates no new warnings. +- [ ] My Pull Request title is in format < issue name > eg Added links in the documentation. +- [ ] I have added tests that prove my fix is effective or that my feature works. + +
+ +## Screenshots (If Applicable) + +
+ + +## Other Information + +Any message for the reviewer or kick off the discussion by explaining why you considered this particular solution, any alternatives etc. diff --git a/doc-site/.github/workflows/ci.yml b/doc-site/.github/workflows/ci.yml new file mode 100644 index 000000000..ddff3e16e --- /dev/null +++ b/doc-site/.github/workflows/ci.yml @@ -0,0 +1,48 @@ +name: ci + +on: + push: + # Publish `main` as latest + branches: + - main + + # Publish `v1.2.3` tags as releases + tags: + - v* + +permissions: + contents: write + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 # fetch all commits/branches + - uses: actions/setup-python@v4 + with: + python-version: 3.x + - uses: actions/cache@v2 + with: + key: ${{ github.ref }} + path: .cache + - name: Install Python dependencies + run: pip install -r ./requirements.txt + - name: Configure git user + run: | + git config --local user.email "github-actions[bot]@users.noreply.github.com" + git config --local user.name "github-actions[bot]" + + - name: Deploy docs + run: | + # Strip git ref prefix from version + echo "${{ github.ref }}" + VERSION=$(echo "${{ github.ref }}" | sed -e 's,.*/\(.*\),\1,') + # Strip "v" prefix from tag name + [[ "${{ github.ref }}" == "refs/tags/"* ]] && ALIAS=$(echo $VERSION | sed -e 's/^v//') + # If building from main, use latest as ALIAS + [ "$VERSION" == "main" ] && ALIAS=latest + echo $VERSION $ALIAS + mike deploy --push --update-aliases $VERSION $ALIAS + mike set-default latest diff --git a/doc-site/.github/workflows/stale.yml b/doc-site/.github/workflows/stale.yml new file mode 100644 index 000000000..33c73913b --- /dev/null +++ b/doc-site/.github/workflows/stale.yml @@ -0,0 +1,21 @@ +name: 'Close stale issues and PRs' +on: + schedule: + - cron: '30 1 * * *' + +jobs: + stale: + runs-on: ubuntu-latest + steps: + - uses: actions/stale@v8 + with: + stale-issue-message: 'This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.' + stale-pr-message: 'This PR is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.' + stale-issue-label: 'stale' + stale-pr-label: 'stale' + close-issue-message: 'This issue was closed because it has been stalled with no activity.' + close-pr-message: 'This PR was closed because it has been stalled with no activity.' + days-before-stale: 30 + days-before-close: 7 + only-labels: 'awaiting response' + ignore-updates: true \ No newline at end of file diff --git a/doc-site/.gitignore b/doc-site/.gitignore new file mode 100644 index 000000000..ba5fac84a --- /dev/null +++ b/doc-site/.gitignore @@ -0,0 +1,2 @@ +.DS_Store +venv diff --git a/docs/config_docs_generate_test.go b/doc-site/config_docs_generate_test.go similarity index 86% rename from docs/config_docs_generate_test.go rename to doc-site/config_docs_generate_test.go index 78b30a971..994162b88 100644 --- a/docs/config_docs_generate_test.go +++ b/doc-site/config_docs_generate_test.go @@ -37,7 +37,7 @@ func TestGenerateConfigDocs(t *testing.T) { coreconfig.Reset() namespace.InitConfig() apiserver.InitConfig() - f, err := os.Create(filepath.Join("reference", "config.md")) + f, err := os.Create(filepath.Join("docs", "reference", "config.md")) assert.NoError(t, err) generatedConfig, err := config.GenerateConfigMarkdown(context.Background(), configDocHeader, config.GetKnownKeys()) assert.NoError(t, err) @@ -48,20 +48,6 @@ func TestGenerateConfigDocs(t *testing.T) { } const configDocHeader = `--- -layout: default title: Configuration Reference -parent: pages.reference -nav_order: 2 ---- - -# Configuration Reference -{: .no_toc } - - - --- ` diff --git a/docs/config_docs_test.go b/doc-site/config_docs_test.go similarity index 87% rename from docs/config_docs_test.go rename to doc-site/config_docs_test.go index 1198788da..80c0b0dbc 100644 --- a/docs/config_docs_test.go +++ b/doc-site/config_docs_test.go @@ -40,7 +40,7 @@ func TestConfigDocsUpToDate(t *testing.T) { apiserver.InitConfig() generatedConfig, err := config.GenerateConfigMarkdown(context.Background(), configDocHeader, config.GetKnownKeys()) assert.NoError(t, err) - configOnDisk, err := os.ReadFile(filepath.Join("reference", "config.md")) + configOnDisk, err := os.ReadFile(filepath.Join("docs", "reference", "config.md")) assert.NoError(t, err) generatedConfigHash := sha1.New() @@ -51,20 +51,6 @@ func TestConfigDocsUpToDate(t *testing.T) { } const configDocHeader = `--- -layout: default title: Configuration Reference -parent: pages.reference -nav_order: 2 ---- - -# Configuration Reference -{: .no_toc } - - - --- ` diff --git a/doc-site/docs/SUMMARY.md b/doc-site/docs/SUMMARY.md new file mode 100644 index 000000000..cb5d3eb3e --- /dev/null +++ b/doc-site/docs/SUMMARY.md @@ -0,0 +1,32 @@ + + +* [Home](index.md) +* Understanding FireFly + * [Introduction](overview/supernode_concept.md) + * [Usage Patterns](overview/usage_patterns.md) + * [Key Features](overview/key_components/index.md) + * overview/key_components/* + * [Web3 Gateway Features](overview/gateway_features.md) + * [Multiparty Features](overview/multiparty/index.md) + * overview/multiparty/* + * [Public and Permissioned](overview/public_vs_permissioned.md) +* [Getting Started](gettingstarted/index.md) + * [β‘  Install the FireFly CLI](gettingstarted/firefly_cli.md) + * [β‘‘ Start your environment](gettingstarted/setup_env.md) + * [β‘’ Use the Sandbox](gettingstarted/sandbox.md) +* Tutorials + * tutorials/* +* Reference + * reference/*.md + * Microservices + * reference/microservices/*.md + * Types + * reference/types/*.md +* Architecture + * architecture/* +* [Contributors](contributors/index.md) + * contributors/* +* [API Spec](swagger/index.md) +* [FAQs](faqs/index.md) +* [Release Notes](releasenotes/index.md) + * releasenotes/* \ No newline at end of file diff --git a/docs/architecture/blockchain_connector_framework.md b/doc-site/docs/architecture/blockchain_connector_framework.md similarity index 59% rename from docs/architecture/blockchain_connector_framework.md rename to doc-site/docs/architecture/blockchain_connector_framework.md index 188935a60..94700538e 100644 --- a/docs/architecture/blockchain_connector_framework.md +++ b/doc-site/docs/architecture/blockchain_connector_framework.md @@ -1,20 +1,8 @@ --- -layout: default title: Blockchain Connector Toolkit -parent: pages.architecture -nav_order: 2 --- # Blockchain Connector Toolkit -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- @@ -41,15 +29,18 @@ called [FireFly Transaction Manager](https://github.com/hyperledger/firefly-tran FFTM is responsible for: - Submission of transactions to blockchains of all types + - Protocol connectivity decoupled with additional lightweight API connector - Easy to add additional protocols that conform to normal patterns of TX submission / events - Monitoring and updating blockchain operations + - Receipts - Confirmations - Extensible transaction handler with capabilities such as: - - Nonce management: idempotent submission of transactions, and assignment of nonces + + - Nonce management: idempotent submission of transactions, and assignment of nonces - Transaction management: pre-signing transactions, resubmission, customizable policy engine - Gas management: Gas Gas station API integration - Transaction process history @@ -64,21 +55,29 @@ FFTM is responsible for: The framework is currently constrained to blockchains that adhere to certain basic principals: 1. Has transactions - - That are signed - - That can optionally have gas semantics (limits and prices, expressed in a blockchain specific way) + +- That are signed +- That can optionally have gas semantics (limits and prices, expressed in a blockchain specific way) + 2. Has events (or "logs") - - That are emitted as a deterministic outcome of transactions + +- That are emitted as a deterministic outcome of transactions + 3. Has blocks - - Containing zero or more transactions, with their associated events - - With a sequential numeric order - - With a hash - - With a parent hash + +- Containing zero or more transactions, with their associated events +- With a sequential numeric order +- With a hash +- With a parent hash + 4. Has finality for transactions & events that can be expressed as a level of confidence over time - - Confirmations: A number of sequential blocks in the canonical chain that contain the transaction + +- Confirmations: A number of sequential blocks in the canonical chain that contain the transaction ## Nonce management in the simple transaction handler The nonces for transactions is assigned as early as possible in the flow: + - Before the REST API for submission of the transaction occurs - After the FFCAPI blockchain connector verifies the transaction can be encoded successfully to the chain - With protection against multiple parallel API requests for the same signing address @@ -134,18 +133,18 @@ The transaction Handler can store custom state in the state store of the FFTM co reported in status within the FireFly API/Explorer on the operation. A reference implementation is provided that: + - Submits transactions via the underlying FFCAPI - Estimates gas price in one of three modes: - Fixed: It is specified via configuration - Connector: The FFCAPI is used to estimate the gas price (e.g. `eth_gasPrice` for EVM JSON/RPC) - Gas Oracle: A REST API is called the the result mapped via a Go template - Re-submits transactions after a configurable stale time -- Record detailed information about [transaction sub-status and actions](../reference/blockchain_operation_status.html) +- Record detailed information about [transaction sub-status and actions](../reference/blockchain_operation_status.md) - Emit customized metrics for transaction processing The reference implementation is available [here](https://github.com/hyperledger/firefly-transaction-manager/blob/main/pkg/txhandler/simple/simple_transaction_handler.go) - ## Event Streams One of the largest pieces of heavy lifting code in the FFTM codebase, is the event stream @@ -169,9 +168,9 @@ Some high architectural principals that informed the code: - Specifies an initial block to listen from, and will replay all events from that block - Can have multiple blockchain specific filters, to match multiple events - The order of delivery _within_ a listener matches the blockchain across all filters - > - Note that the EVMConnect implementation of FFCAPI attempts to make this true across all listeners - > on an event stream. However, this is impossible when a new listener has been added, - > and that listener is catching up from an old block. + > - Note that the EVMConnect implementation of FFCAPI attempts to make this true across all listeners + > on an event stream. However, this is impossible when a new listener has been added, + > and that listener is catching up from an old block. - Compatibility - Has breaking changes from the API of EthConnect - A component that has been upgraded to support EVMConnect, @@ -190,3 +189,96 @@ Some high architectural principals that informed the code: [![FireFly Connector Toolkit Event Streams](../images/firefly_connector_toolkit_event_streams.jpg)](../images/firefly_connector_toolkit_event_streams.jpg) +## Blockchain error messages + +The receipt for a FireFly blockchain operation contains an `extraInfo` section that records additional information about the transaction. For example: + +``` +"receipt": { + ... + "extraInfo": [ + { + { + "contractAddress":"0x87ae94ab290932c4e6269648bb47c86978af4436", + "cumulativeGasUsed":"33812", + "from":"0x2b1c769ef5ad304a4889f2a07a6617cd935849ae", + "to":"0x302259069aaa5b10dc6f29a9a3f72a8e52837cc3", + "gasUsed":"33812", + "status":"0", + "errorMessage":"Not enough tokens", + } + } + ], + ... +}, +``` + +The `errorMessage` field can be be set by a blockchain connector to provide FireFly and the end-user with more information about the reason why a tranasction failed. The blockchain connector can choose what information to include in `errorMessage` field. It may be set to an error message relating to the blockchain connector itself or an error message passed back from the blockchain or smart contract that was invoked. + +### Format of a `firefly-evmconnect` error message + +The following section describes the way that the `firefly-evmconnect` plugin uses the `errorMessage` field. This serves both as an explanation of how EVM-based transaction errors will be formatted, and as a guide that other blockchain connectors may decide to follow. + +The `errorMessage` field for a `firefly-evmconnect` transaction may contain one of the following: + +1. An error message from the FireFly blockchain connector + +- For example `"FF23054", "Error return value unavailable"` + +2. A decoded error string from the blockchain transaction + +- For example `Not enough tokens` +- This could be an error string from a smart contract e.g. `require(requestedTokens <= allowance, "Not enough tokens");` + +3. An un-decoded byte string from the blockchain transaction + +- For example + +``` +FF23053: Error return value for custom error: 0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010 +``` + +- This could be a custom error from a smart contract e.g. + +``` +error AllowanceTooSmall(uint256 requested, uint256 allowance); +... +revert AllowanceTooSmall({ requested: 100, allowance: 20 }); +``` + +- If an error reason cannot be decoded the `returnValue` of the `extraInfo` will be set to the raw byte string. For example: + +``` +"receipt": { + ... + "extraInfo": [ + { + { + "contractAddress":"0x87ae94ab290932c4e6269648bb47c86978af4436", + "cumulativeGasUsed":"33812", + "from":"0x2b1c769ef5ad304a4889f2a07a6617cd935849ae", + "to":"0x302259069aaa5b10dc6f29a9a3f72a8e52837cc3", + "gasUsed":"33812", + "status":"0", + "errorMessage":"FF23053: Error return value for custom error: 0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010", + "returnValue":"0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010" + } + } + ], + ... +}, +``` + +### Retrieving EVM blockchain transaction errors + +The ability of a blockchain connector such as `firefly-evmconnect` to retrieve the reason for a transaction failure, is dependent on by the configuration of the blockchain it is connected to. For an EVM blockchain the reason why a transaction failed is recorded with the `REVERT` op code, with a `REASON` set to the reason for the failure. By default, most EVM clients do not store this reason in the transaction receipt. This is typically to reduce resource consumption such as memory usage in the client. It is usually possible to configure an EVM client to store the revert reason in the transaction receipt. For example Hyperledger Besuβ„’ provides the `--revert-reason-enabled` configuration option. If the transaction receipt does not contain the revert reason it is possible to request that an EVM client re-run the transaction and return a trace of all of the op-codes, including the final `REVERT` `REASON`. This can be a resource intensive request to submit to an EVM client, and is only available on archive nodes or for very recent blocks. + +The `firefly-evmconnect` blockchain connector attempts to obtain the reason for a transaction revert and include it in the `extraInfo` field. It uses the following mechanisms, in this order: + +1. Checks if the blockchain transaction receipt contains the revert reason. +2. If the revert reason is not in the receipt, and the `connector.traceTXForRevertReason` configuration option is set to `true`, calls `debug_traceTransaction` to obtain a full trace of the transaction and extract the revert reason. By default, `connector.traceTXForRevertReason` is set to `false` to avoid submitting high-resource requests to the EVM client. + +If the revert reason can be obtained using either mechanism above, the revert reason bytes are decoded in the following way: + +- Attempts to decode the bytes as the standard `Error(string)` signature format and includes the decoded string in the `errorMessage` +- If the reason is not a standard `Error(String)` error, sets the `errorMessage` to `FF23053: Error return value for custom error: ` and includes the raw byte string in the `returnValue` field. diff --git a/docs/architecture/internal_event_sequencing.md b/doc-site/docs/architecture/internal_event_sequencing.md similarity index 65% rename from docs/architecture/internal_event_sequencing.md rename to doc-site/docs/architecture/internal_event_sequencing.md index fac734f81..bcb745a46 100644 --- a/docs/architecture/internal_event_sequencing.md +++ b/doc-site/docs/architecture/internal_event_sequencing.md @@ -1,20 +1,8 @@ --- -layout: default title: Internal Event Sequencing -parent: pages.architecture -nav_order: 6 --- # Internal Event Sequencing -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- @@ -22,12 +10,13 @@ nav_order: 6 ![Internal Event Sequencing](../images/internal_event_sequencing.jpg "Internal Event Sequencing") -One of the most important roles FireFly has, is to take actions being performed by the local apps, process them, get them confirmed, and then deliver back +One of the most important roles FireFly has, is to take actions being performed by the local apps, process them, get them confirmed, and then deliver back as "stream of consciousness" to the application alongside all the other events that are coming into the application from other FireFly Nodes in the network. You might observe the problems solved in this architecture are similar to those in a message queuing system (like Apache Kafka, or a JMS/AMQP provider like ActiveMQ etc.). However, we cannot directly replace the internal logic with such a runtime - because FireFly's job is to aggregate data from multiple runtimes that behave similarly to these: + - Private messaging in the Data Exchange - The blockchain ledger(s) themselves, which are a stream of sequenced events - The event dispatcher delivering messages to applications that have been sequenced by FireFly @@ -35,38 +24,39 @@ However, we cannot directly replace the internal logic with such a runtime - bec So FireFly provides the convenient REST based management interface to simplify the world for application developers, by aggregating the data from multiple locations, and delivering it to apps in a deterministic sequence. The sequence is made deterministic: + - Globally to all apps within the scope of the ledger, when a Blockchain ledger is used to pin events (see #10) - Locally for messages delivered through a single FireFly node into the network -- Locally for all messages delivered to applications connected to a FireFly node, across blockchain +- Locally for all messages delivered to applications connected to a FireFly node, across blockchain ## App Instances -* Broadcast messages to the network -* Ingest ack when message persisted in local messages table -* Consume events via Websocket connection into FireFly +- Broadcast messages to the network +- Ingest ack when message persisted in local messages table +- Consume events via Websocket connection into FireFly ## Outbound Sequencers -* Broadcast or Private through IPFS or Private Data Storage -* Long-running leader-elected jobs listening to the database (via event tables in SQL, etc.) +- Broadcast or Private through IPFS or Private Data Storage +- Long-running leader-elected jobs listening to the database (via event tables in SQL, etc.) -## Inbound Aggregator +## Inbound Aggregator -* Triggered each time an event is detected by the associated plugin. -* It is the responsibility of the plugin to fire events sequentially. Can be workload managed but **must** be sequential. +- Triggered each time an event is detected by the associated plugin. +- It is the responsibility of the plugin to fire events sequentially. Can be workload managed but **must** be sequential. ### Events Table -* Deliberately lightweight persisted object, that is generated as a byproduct of other persistent actions. -* Records the local sequence of a specific event within the local node. -* The highest level event type is the confirmation of a message, however the table can be extended for more granularity on event types. +- Deliberately lightweight persisted object, that is generated as a byproduct of other persistent actions. +- Records the local sequence of a specific event within the local node. +- The highest level event type is the confirmation of a message, however the table can be extended for more granularity on event types. ## Subscription Manager -* Responsible for filtering and delivering batches of events to the active event dispatchers. -* Records the latest offset confirmed by each dispatcher. +- Responsible for filtering and delivering batches of events to the active event dispatchers. +- Records the latest offset confirmed by each dispatcher. ## Event Dispatcher -* Created with leadership election when WebSocket connection is made from an app into FireFly. -* Extensible to other dispatchers (AMQP, etc.). +- Created with leadership election when WebSocket connection is made from an app into FireFly. +- Extensible to other dispatchers (AMQP, etc.). diff --git a/doc-site/docs/architecture/multiparty_event_sequencing.md b/doc-site/docs/architecture/multiparty_event_sequencing.md new file mode 100644 index 000000000..b7f725df3 --- /dev/null +++ b/doc-site/docs/architecture/multiparty_event_sequencing.md @@ -0,0 +1,33 @@ +--- +title: Multiparty Event Sequencing +--- + +# Multiparty Event Sequencing + + + +[![Multiparty Event Sequencing](../images/global_sequencing.svg "Multiparty Event Sequencing")](../images/global_sequencing.svg) + +## Transaction Submission + +- An individual FireFly instance preserves the order that it received messages from application instances. +- Where possible, batching is used to roll-up hundreds of transactions into a single blockchain transaction. +- _Blockchain allows these messages to be globally sequenced with messages submitted by other members of the network._ + +## Blockchain Ordering + +- All member FireFly runtimes see every transaction in the same sequence. +- _This includes when transactions are being submitted by both sides concurrently._ + +## Message Assembly + +- A queue of events is maintained for each matching app subscription. +- The public/private payloads travel separately to the blockchain, and arrive at different times. FireFly assembles these together prior to delivery. +- If data associated with a blockchain transaction is late, or does not arrive, all messages on the same "context" will be blocked. +- _It is good practice to send messages that don't need to be processed in order, with different "context" fields. For example use the ID of your business transaction, or other long-running process / customer identifier._ + +## Event Processing + +- Events are processed consistently by all parties. +- All FireFly runtimes see every event that they are subscribed to, in the same sequence. +- _The submitter must also apply the logic only in the sequence ordered by the blockhain. It cannot assume the order even if it is the member that submitted it._ diff --git a/docs/architecture/node_component_architecture.md b/doc-site/docs/architecture/node_component_architecture.md similarity index 95% rename from docs/architecture/node_component_architecture.md rename to doc-site/docs/architecture/node_component_architecture.md index c8d564aaf..413f027c1 100644 --- a/docs/architecture/node_component_architecture.md +++ b/doc-site/docs/architecture/node_component_architecture.md @@ -1,20 +1,8 @@ --- -layout: default title: Node Component Architecture -parent: pages.architecture -nav_order: 1 --- # Node Component Architecture -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- diff --git a/docs/architecture/ping_pong_txflow.md b/doc-site/docs/architecture/ping_pong_txflow.md similarity index 90% rename from docs/architecture/ping_pong_txflow.md rename to doc-site/docs/architecture/ping_pong_txflow.md index 3660b46e8..a6288b205 100644 --- a/docs/architecture/ping_pong_txflow.md +++ b/doc-site/docs/architecture/ping_pong_txflow.md @@ -1,24 +1,12 @@ --- -layout: default title: Example Transaction Flow -parent: pages.architecture -nav_order: 5 --- # Example Transaction Flow (Ping Pong) -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## Overview +## Overview [![Simple Ping Pong Tx Flow](../images/ping_pong.svg "Simple Ping Pong Tx Flow")](../images/ping_pong.svg) @@ -29,30 +17,32 @@ This demonstrates the problem that at its core FireFly is there to solve. The in - Party A: Broadcast some information about that asset to everyone, using blockchain to record, sequence and propagate. - So people can find it, or part of a more sophisticated workflow. - Party B: Request the actual data - with evidence of that request tied to the blockchain. - - Including some *private* data that's sent to the Party A, reliably off-chain. -- Party A: Authorize the request, and send the data *privately* to Party B. + - Including some _private_ data that's sent to the Party A, reliably off-chain. +- Party A: Authorize the request, and send the data _privately_ to Party B. - In this example there's no blockchain involved in this step. This is the kind of thing that enterprise projects have been solving ground-up since the dawn of enterprise blockchain, and the level of engineering required that is completely detached from business value, is very high. The "tramlines" view shows how FireFly's pluggable model makes the job of the developer really simple: + - A few simple API calls from a modern web app. - Event triggered execution of application logic. This is deliberately a simple flow, and all kinds of additional layers might well layer on (and fit within the FireFly model): + - NFTs to track ownership etc. related to the digital asset. - Tokenized rewards/payments integrated with the authorization of the transfer of data. - Proof of deterministic execution of the logic to perform the authorization (on-chain, TEEs, ZKPs). - Human workflow, that is of course completely non-deterministic. - Multiple additional process steps, deterministic or not. - Inclusion of multiple additional parties (maybe it's a request-for-tender, submit-tender flow for example). -- etc. +- etc. ## Broadcast Public Description of Binary Data Asset (Member 1) - Upload Blob of the actual data - Returns a hash of the payload -- Upload JSON containing the public index data +- Upload JSON containing the public index data - Includes the hash of the full payload - Send a broadcast message with the public index data - Agree upon a primary key of the data as the "context" diff --git a/docs/architecture/plugin_architecture.md b/doc-site/docs/architecture/plugin_architecture.md similarity index 76% rename from docs/architecture/plugin_architecture.md rename to doc-site/docs/architecture/plugin_architecture.md index 67ba02cda..8b55ff705 100644 --- a/docs/architecture/plugin_architecture.md +++ b/doc-site/docs/architecture/plugin_architecture.md @@ -1,24 +1,13 @@ --- -layout: default title: Plugin Architecture -parent: pages.architecture -nav_order: 4 --- # Plugin Architecture -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- --- + ![FireFly Plugin Architecture](../images/firefly_plugin_architecture.svg "FireFly Plugin Architecture") This diagram shows the various plugins that are currently in the codebase and the layers in each plugin @@ -30,21 +19,23 @@ This diagram shows the details of what goes into each layer of a FireFly plugin --- ## Overview -The FireFly node is built for extensibility, with separate pluggable runtimes orchestrated into a common API for developers. The mechanics of that + +The FireFly node is built for extensibility, with separate pluggable runtimes orchestrated into a common API for developers. The mechanics of that pluggability for developers of new connectors is explained below: This architecture is designed to provide separations of concerns to account for: + - Differences in code language for the low-level connection to a backend (Java for Corda for example) - Differences in transports, particularly for delivery of events: - Between FireFly Core and the Connector - Different transports other than HTTPS/WebSockets (GRPC etc.), and different wire protocols (socket.io, etc.) - Between the Connector and the underlying Infrastructure Runtime - - Often this is heavy lifting engineering within the connector + - Often this is heavy lifting engineering within the connector - Differences in High Availability (HA) / Scale architectures - - Between FireFly Core, and the Connector - - Often for event management, and active/passive connector runtime is sufficient - - Between the Connector and the Infrastructure Runtime - - The infrastructure runtimes have all kinds of variation here... think of the potential landscape here from PostreSQL through Besu/Fabric/Corda, to Hyperledger Avalon and even Main-net ethereum + - Between FireFly Core, and the Connector + - Often for event management, and active/passive connector runtime is sufficient + - Between the Connector and the Infrastructure Runtime + - The infrastructure runtimes have all kinds of variation here... think of the potential landscape here from PostreSQL through Besu/Fabric/Corda, to Hyperledger Avalon and even Main-net ethereum ## FireFly Core @@ -80,7 +71,7 @@ This architecture is designed to provide separations of concerns to account for: ## Infrastructure Runtime - Besu, Quorum, Corda, Fabric, IPFS, Kafka, etc. -- Runs/scales independently from FF Core -- Coded in any language, OSS or proprietary +- Runs/scales independently from FF Core +- Coded in any language, OSS or proprietary - Not specific to FireFly - HA model can be active/passive or active/active diff --git a/docs/FireFly-Logo.svg b/doc-site/docs/assets/FireFly-Logo.svg similarity index 100% rename from docs/FireFly-Logo.svg rename to doc-site/docs/assets/FireFly-Logo.svg diff --git a/doc-site/docs/assets/FireFly_Logo_White.svg b/doc-site/docs/assets/FireFly_Logo_White.svg new file mode 100644 index 000000000..9b8776e1f --- /dev/null +++ b/doc-site/docs/assets/FireFly_Logo_White.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/favicon.ico b/doc-site/docs/assets/favicon.ico similarity index 100% rename from docs/favicon.ico rename to doc-site/docs/assets/favicon.ico diff --git a/doc-site/docs/assets/project-icon.png b/doc-site/docs/assets/project-icon.png new file mode 100755 index 000000000..7266b044e Binary files /dev/null and b/doc-site/docs/assets/project-icon.png differ diff --git a/doc-site/docs/assets/project-logo.png b/doc-site/docs/assets/project-logo.png new file mode 100644 index 000000000..3075f9a77 Binary files /dev/null and b/doc-site/docs/assets/project-logo.png differ diff --git a/docs/contributors/advanced_cli_usage.md b/doc-site/docs/contributors/advanced_cli_usage.md similarity index 96% rename from docs/contributors/advanced_cli_usage.md rename to doc-site/docs/contributors/advanced_cli_usage.md index 5a8b1af33..bb52d7dbd 100644 --- a/docs/contributors/advanced_cli_usage.md +++ b/doc-site/docs/contributors/advanced_cli_usage.md @@ -1,27 +1,13 @@ --- -layout: i18n_page -title: pages.advanced_cli_usage -parent: pages.contributors -nav_order: 5 ---- - -# Advanced CLI Usage - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - +title: Advanced CLI Usage --- This page details some of the more advanced options of the FireFly CLI ---- - ## Understanding how the CLI uses FireFly releases ## The `manifest.json` file + FireFly has a [`manifest.json` file in the root of the repo](https://github.com/hyperledger/firefly/blob/main/manifest.json). This file contains a list of versions (both tag and sha) for each of the microservices that should be used with this specific commit. Here is an example of what the `manifest.json` looks like: @@ -52,9 +38,11 @@ Here is an example of what the `manifest.json` looks like: ``` ## Default CLI behavior for releases + When creating a new stack, the CLI will by default, check the latest non-pre-release version of FireFly and look at its `manifest.json` file that was part of that commit. It will then use the Docker images referenced in that file to determine which images it should pull for the new stack. The specific image tag and sha is written to the `docker-compose.yml` file for that stack, so restarting or resetting a stack will never pull a newer image. ## Running a specific release of FireFly + If you need to run some other version that is not the latest release of FireFly, you can tell the FireFly CLI which release to use by using the `--release` or `-r` flag. For example, to explicitly use `v0.9.0` run this command to initialize the stack: ``` @@ -62,6 +50,7 @@ ff init -r v0.9.0 ``` ## Running an unreleased version of one or more services + If you need to run an unreleased version of FireFly or one of its microservices, you can point the CLI to a specific `manifest.json` on your local disk. To do this, use the `--manifest` or `-m` flag. For example, if you have a file at `~/firefly/manifest.json`: ``` @@ -71,6 +60,7 @@ ff init -m ~/firefly/manifest.json If you need to test a locally built docker image of a specific service, you'll want to edit the `manifest.json` before running `ff init`. Let's look at an example where we want to run a locally built version of fabconnect. The same steps apply to any of FireFly's microservices. ### Build a new image of fabconnect locally + From the fabconnect project directory, build and tag a new Docker image: ``` @@ -78,6 +68,7 @@ docker build -t ghcr.io/hyperledger/firefly-fabconnect . ``` ### Edit your `manifest.json` file + Next, edit the `fabconnect` section of the `manifest.json` file. You'll want to remove the `tag` and `sha` and a `"local": true` field, so it looks like this: ```json @@ -90,6 +81,7 @@ Next, edit the `fabconnect` section of the `manifest.json` file. You'll want to ``` ### Initialize the stack with the custom `manifest.json` file + ``` ff init local-test -b fabric -m ~/Code/hyperledger/firefly/manifest.json ff start local-test @@ -101,10 +93,11 @@ If you are iterating on changes locally, you can get the CLI to use an updated i - If you've already run the stack, you can run `ff reset ` and `ff start ` to reset the data, and use the newer image ## Running a locally built FireFly Core image -You may have noticed that FireFly core is actually not listed in the `manifest.json file`. If you want to run a locally built image of FireFly Core, you can follow the same steps above, but instead of editing an existing section in the file, we'll add a new one for FireFly. +You may have noticed that FireFly core is actually not listed in the `manifest.json file`. If you want to run a locally built image of FireFly Core, you can follow the same steps above, but instead of editing an existing section in the file, we'll add a new one for FireFly. ### Build a new image of FireFly locally + From the firefly project directory, build and tag a new Docker image: ``` @@ -112,6 +105,7 @@ make docker ``` ### Initialize the stack with the custom `manifest.json` file + ``` ff init local-test -m ~/Code/hyperledger/firefly/manifest.json ff start local-test diff --git a/docs/contributors/code_hierarchy.md b/doc-site/docs/contributors/code_hierarchy.md similarity index 97% rename from docs/contributors/code_hierarchy.md rename to doc-site/docs/contributors/code_hierarchy.md index 227438313..051508a9b 100644 --- a/docs/contributors/code_hierarchy.md +++ b/doc-site/docs/contributors/code_hierarchy.md @@ -1,20 +1,8 @@ --- -layout: i18n_page -title: pages.code_hierarchy -parent: pages.contributors -nav_order: 2 +title: Code Hierarchy --- -# Firefly Code Hierarchy -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- +# FireFly Code Hierarchy Use the following diagram to better understand the hierarchy amongst the core FireFly components, plugins and utility frameworks: @@ -143,9 +131,9 @@ Use the following diagram to better understand the hierarchy amongst the core Fi β”‚ β”‚ β”‚ manager β”‚ * Non-fungible tokens: NFTs / globally uniqueness / digital twins β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ * Full indexing of transaction history β”‚ β”‚ [REST/WebSockets] - β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€ + β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€ β”‚ β”‚ β”‚ ERC-20 / ERC-721 β”œβ”€β”€β”€β”€ ERC-1155 β”œβ”€β”€β”€β”€ Simple framework for building token connectors - β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ └─ + β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ └─ β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”œβ”€β”€β”€β”€ sync / [Sa] β”‚ - Sync/Async Bridge @@ -179,18 +167,18 @@ Plugins: Each plugin comprises a Go shim, plus a remote agent microservice runti β”‚ β”‚ ethereum β”‚ β”‚ fabric β”‚ β”‚ corda/cordapps β”‚ β”‚ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ [REST/WebSockets] - β”‚ β”Œβ”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€ + β”‚ β”Œβ”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€ β”‚ β”‚ transaction manager [Tm] β”œβ”€β”€β”€β”€ Connector API [ffcapi] β”œβ”€β”€β”€β”€ Simple framework for building blockchain connectors - β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ └─ - β”‚ + β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ └─ + β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - Token interface β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ tokens [Ti]β”‚ * Standardizes core concepts: token pools, transfers, approvals β”‚ β”‚ interface β”‚ * Pluggable across token standards β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ * Supports simple implementation of custom token standards via microservice connector β”‚ [REST/WebSockets] - β”‚ β”Œβ”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€ + β”‚ β”Œβ”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€ β”‚ β”‚ ERC-20 / ERC-721 β”œβ”€β”€β”€β”€ ERC-1155 β”œβ”€β”€β”€β”€ Simple framework for building token connectors - β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ └─ + β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ └─ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - P2P Content Addresssed Filesystem β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ shared [Si]β”‚ * Payload upload / download diff --git a/docs/contributors/code_overview.md b/doc-site/docs/contributors/code_overview.md similarity index 91% rename from docs/contributors/code_overview.md rename to doc-site/docs/contributors/code_overview.md index 604073f17..73e0d9d9d 100644 --- a/docs/contributors/code_overview.md +++ b/doc-site/docs/contributors/code_overview.md @@ -1,20 +1,8 @@ --- -layout: i18n_page -title: pages.code_overview -parent: pages.contributors -nav_order: 1 +title: Code Overview --- -# Firefly Code Overview -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- +# FireFly Code Overview ## Developer Intro @@ -49,6 +37,7 @@ A few highlights: - Better search, filter and query support ## Directories + - [internal](https://github.com/hyperledger/firefly/tree/main/internal): The core Golang implementation code - [pkg](https://github.com/hyperledger/firefly/tree/main/pkg): Interfaces intended for external project use - [cmd](https://github.com/hyperledger/firefly/tree/main/cmd): The command line entry point diff --git a/docs/contributors/code_repositories.md b/doc-site/docs/contributors/code_repositories.md similarity index 86% rename from docs/contributors/code_repositories.md rename to doc-site/docs/contributors/code_repositories.md index 967aafd89..4ccd302a7 100644 --- a/docs/contributors/code_repositories.md +++ b/doc-site/docs/contributors/code_repositories.md @@ -1,19 +1,5 @@ --- -layout: i18n_page -title: pages.code_repositories -parent: pages.contributors -nav_order: 3 ---- - -# Code Repositories -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - +title: Code Repositories --- FireFly has a plugin based architecture design, with a microservice runtime footprint. diff --git a/docs/contributors/dev_environment_setup.md b/doc-site/docs/contributors/dev_environment_setup.md similarity index 93% rename from docs/contributors/dev_environment_setup.md rename to doc-site/docs/contributors/dev_environment_setup.md index 254496bcc..c4385d81e 100644 --- a/docs/contributors/dev_environment_setup.md +++ b/doc-site/docs/contributors/dev_environment_setup.md @@ -1,20 +1,9 @@ --- -layout: default title: Setting up a FireFly Core Development Environment -parent: pages.contributors -nav_order: 4 --- # Setting up a FireFly Core Development Environment -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- - This guide will walk you through setting up your machine for contributing to FireFly, specifically the FireFly core. --- @@ -38,8 +27,8 @@ We recommend following the [instructions on golang.org](https://golang.org/doc/i After installing Go, you will need to add a few environment variables to your shell run commands file. This is usually a hidden file in your home directory called `.bashrc` or `.zshrc`, depending on which shell you're using. - Add the following lines to your `.bashrc` or `.zshrc` file: + ``` export GOPATH=$HOME/go export GOROOT="/usr/local/go" @@ -96,7 +85,8 @@ ff start dev At a certain point in the startup process, the CLI will pause and wait for up to two minutes for you to start the other FireFly node. There are two different ways you can run the external FireFly core process. ### 1) From another terminal -The CLI will print out the command line which can be copied and pasted into another terminal window to run FireFly. *This command should be run from the `firefly` core project directory.* Here is an example of the command that the CLI will tell you to run: + +The CLI will print out the command line which can be copied and pasted into another terminal window to run FireFly. _This command should be run from the `firefly` core project directory._ Here is an example of the command that the CLI will tell you to run: ``` firefly -f ~/.firefly/stacks/dev/runtime/config/firefly_core_0.yml @@ -104,18 +94,16 @@ firefly -f ~/.firefly/stacks/dev/runtime/config/firefly_core_0.yml > **NOTE**: The first time you run FireFly with a fresh database, it will need a directory of database migrations to apply to the empty database. If you run FireFly from the `firefly` project directory you cloned from GitHub, it will automatically find these and apply them. If you run it from some other directory, you will have to point FireFly to the migrations on your own. - ### 2) Using an IDE -If you named your stack `dev` there is a `launch.json` file for Visual Studio code already in the project directory. If you have the project open in Visual Studio Code, you can either press the F5 key to run it, or go to the "Run and Debug" view in Visual Studio code, and click "Run FireFly Core". +If you named your stack `dev` there is a `launch.json` file for Visual Studio code already in the project directory. If you have the project open in Visual Studio Code, you can either press the F5 key to run it, or go to the "Run and Debug" view in Visual Studio code, and click "Run FireFly Core". ![Launch config](../images/launch_config.png "Launch config") Now you should have a full FireFly stack up and running, and be able to debug FireFly using your IDE. Happy hacking! - > **NOTE**: Because `firefly-ui` is a separate repo, unless you also start a UI dev server for the external FireFly core, the default UI path will not load. This is expected, and if you're just working on FireFly core itself, you don't need to worry about it.` ## Set up dev environment for other components -Refer to [Advanced CLI Usage](./advanced_cli_usage.md). \ No newline at end of file +Refer to [Advanced CLI Usage](./advanced_cli_usage.md). diff --git a/doc-site/docs/contributors/docs_setup.md b/doc-site/docs/contributors/docs_setup.md new file mode 100644 index 000000000..5ba0d463c --- /dev/null +++ b/doc-site/docs/contributors/docs_setup.md @@ -0,0 +1,99 @@ +--- +title: Contributing to Documentation +--- + +# Contributing to Documentation + +This guide will walk you through setting up your machine for contributing to FireFly documentation. Documentation contributions are extremely valuable. If you discover something is missing in the docs, we would love to include your additions or clarifications to help the next person who has the same question. + +This doc site is generated by a set of [Markdown](https://daringfireball.net/projects/markdown/) files in the main FireFly repository, under the `./doc-site` directory. You can browse the source for the current live site in GitHub here: [https://github.com/hyperledger/firefly/tree/main/doc-site](https://github.com/hyperledger/firefly/tree/main/doc-site) + +--- + +## Process for updating documentation + +The process for updating the documentation is really easy! You'll follow the same basic steps outlined in the same [steps outlined in the Contributor's guide](./index.md#-make-changes). Here are the detailed steps for contributing to the docs: + +1. Fork [https://github.com/hyperledger/firefly](https://github.com/hyperledger/firefly) +2. Clone your fork locally to your computer +3. Follow the steps below to view your local copy of the docs in a browser +4. Make some improvements to the Markdown files +5. Verify that your changes look they way you want them to in your browser +6. Create a new git commit with your changes. Be sure to sign-off on your commit by using `git commit -s`! +7. Push your changes +8. [Open a Pull Request](https://github.com/hyperledger/firefly/compare) to incorporate your changes back into the hyperledger/firefly repo + +--- + +This FireFly documentation site is based on the [Hyperledger documentation template](https://github.com/hyperledger-labs/documentation-template). The template utilizes MkDocs (documentation at [mkdocs.org](https://www.mkdocs.org)) and the theme Material for MkDocs (documentation at [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)). Material adds a number of extra features to MkDocs, and Hyperledger repositories can take advantage of the theme's [Insiders](https://squidfunk.github.io/mkdocs-material/insiders/) capabilities. + +[Material for MkDocs]: https://squidfunk.github.io/mkdocs-material/ +[Mike]: https://github.com/jimporter/mike + +## Prerequisites + +To test the documents and update the published site, the following tools are needed: + +- A Bash shell +- git +- Python 3 +- The [Material for Mkdocs] theme. +- The [Mike] MkDocs plugin for publishing versions to gh-pages. + - Not used locally, but referenced in the `mkdocs.yml` file and needed for + deploying the site to gh-pages. + +### git + +`git` can be installed locally, as described in the [Install Git Guide from GitHub](https://github.com/git-guides/install-git). + +### Python 3 + +`Python 3` can be installed locally, as described in the [Python Getting Started guide](https://www.python.org/about/gettingstarted/). + +### Virtual environment + +It is recommended to install your Python dependencies in a virtual environment in case you have other conflicting Python installations on your machine. This also removes the need to install these packages globally on your computer. + +```bash +cd doc-site +python3 -m venv venv +source venv/bin/activate +``` + +### Mkdocs + +The Mkdocs-related items can be installed locally, as described in the [Material +for Mkdocs] installation instructions. The short, case-specific version of those +instructions follow: + +```bash +pip install -r requirements.txt +``` + +### Verify Setup + +To verify your setup, check that you can run `mkdocs` by running the command `mkdocs --help` to see the help text. + +## Useful MkDocs Commands + +The commands you will usually use with `mkdocs` are: + +- `mkdocs serve` - Start the live-reloading docs server. +- `mkdocs build` - Build the documentation site. +- `mkdocs -h` - Print help message and exit. + +## Adding Content + +The basic process for adding content to the site is: + +- Create a new markdown file under the `docs` folder +- Add the new file to the table of contents (`nav` section in the `mkdocs.yml` file) + +If you are using this as a template for creating your own documentation, please see [the instructions for customization](./docs/index.md). + +## Repository layout + + mkdocs.yml # The configuration file. + docs/ + index.md # The documentation homepage. + ... # Other markdown pages, images and other files. diff --git a/docs/contributors/index.md b/doc-site/docs/contributors/index.md similarity index 95% rename from docs/contributors/index.md rename to doc-site/docs/contributors/index.md index eb2cd1265..0f5d0f5fe 100644 --- a/docs/contributors/index.md +++ b/doc-site/docs/contributors/index.md @@ -1,19 +1,5 @@ --- -layout: i18n_page -title: pages.contributors -nav_order: 7 -has_children: true ---- - -# Contributors' Guide -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - +title: Contributors' Guide --- We welcome anyone to contribute to the FireFly project! If you're interested, this is a guide on how to get started. **You don't have to be a blockchain expert to make valuable contributions!** There are lots of places for developers of all experience levels to get involved. @@ -23,51 +9,62 @@ We welcome anyone to contribute to the FireFly project! If you're interested, th --- ## πŸš€ Connect with us on Discord + You can chat with maintainers and other contributors on Discord in the `firefly` channel: [https://discord.gg/hyperledger](https://discord.gg/hyperledger) -[Join Discord Server](https://discord.gg/hyperledger){: .btn .btn-purple .mb-5} +[Join Discord Server](https://discord.gg/hyperledger){: .md-button .md-button--primary} ## πŸ“… Join our Community Calls + Community calls are a place to talk to other contributors, maintainers, and other people interested in FireFly. Maintainers often discuss upcoming changes and proposed new features on these calls. These calls are a great way for the community to give feedback on new ideas, ask questions about FireFly, and hear how others are using FireFly to solve real world problems. Please see the [FireFly Calendar](https://lists.hyperledger.org/g/firefly/calendar) for the current meeting schedule, and the link to join. Everyone is welcome to join, regardless of background or experience level. ## πŸ” Find your first issue + If you're looking for somewhere to get started in the FireFly project and want something small and relatively easy, take a look at [issues tagged with "Good first issue"](https://github.com/search?q=repo%3Ahyperledger%2Ffirefly+repo%3Ahyperledger%2Ffirefly-ethconnect+repo%3Ahyperledger%2Ffirefly-evmconnect+repo%3Ahyperledger%2Ffirefly-fabconnect+repo%3Ahyperledger%2Ffirefly-cordaconnect+repo%3Ahyperledger%2Ffirefly-transaction-manager+repo%3Ahyperledger%2Ffirefly-cli+repo%3Ahyperledger%2Ffirefly-samples+repo%3Ahyperledger%2Ffirefly-dataexchange-https+repo%3Ahyperledger%2Ffirefly-ui+repo%3Ahyperledger%2Ffirefly-helm-charts+repo%3Ahyperledger%2Ffirefly-sandbox+repo%3Ahyperledger%2Ffirefly-signer+repo%3Ahyperledger%2Ffirefly-common+repo%3Ahyperledger%2Ffirefly-perf-cli+repo%3Ahyperledger%2Ffirefly-tokens-erc1155+repo%3Ahyperledger%2Ffirefly-tokens-erc20-erc721+repo%3Ahyperledger%2Ffirefly-sdk-nodejs+label%3A%22Good+first+issue%22+state%3Aopen&type=Issues&ref=advsearch&l=&l=). You can definitely work on other things if you want to. These are only suggestions for easy places to get started. -[See "Good First Issues"](https://github.com/search?q=repo%3Ahyperledger%2Ffirefly+repo%3Ahyperledger%2Ffirefly-ethconnect+repo%3Ahyperledger%2Ffirefly-evmconnect+repo%3Ahyperledger%2Ffirefly-fabconnect+repo%3Ahyperledger%2Ffirefly-cordaconnect+repo%3Ahyperledger%2Ffirefly-transaction-manager+repo%3Ahyperledger%2Ffirefly-cli+repo%3Ahyperledger%2Ffirefly-samples+repo%3Ahyperledger%2Ffirefly-dataexchange-https+repo%3Ahyperledger%2Ffirefly-ui+repo%3Ahyperledger%2Ffirefly-helm-charts+repo%3Ahyperledger%2Ffirefly-sandbox+repo%3Ahyperledger%2Ffirefly-signer+repo%3Ahyperledger%2Ffirefly-common+repo%3Ahyperledger%2Ffirefly-perf-cli+repo%3Ahyperledger%2Ffirefly-tokens-erc1155+repo%3Ahyperledger%2Ffirefly-tokens-erc20-erc721+repo%3Ahyperledger%2Ffirefly-sdk-nodejs+label%3A%22Good+first+issue%22+state%3Aopen&type=Issues&ref=advsearch&l=&l=){: .btn .btn-purple .mb-5} +[See "Good First Issues"](https://github.com/search?q=repo%3Ahyperledger%2Ffirefly+repo%3Ahyperledger%2Ffirefly-ethconnect+repo%3Ahyperledger%2Ffirefly-evmconnect+repo%3Ahyperledger%2Ffirefly-fabconnect+repo%3Ahyperledger%2Ffirefly-cordaconnect+repo%3Ahyperledger%2Ffirefly-transaction-manager+repo%3Ahyperledger%2Ffirefly-cli+repo%3Ahyperledger%2Ffirefly-samples+repo%3Ahyperledger%2Ffirefly-dataexchange-https+repo%3Ahyperledger%2Ffirefly-ui+repo%3Ahyperledger%2Ffirefly-helm-charts+repo%3Ahyperledger%2Ffirefly-sandbox+repo%3Ahyperledger%2Ffirefly-signer+repo%3Ahyperledger%2Ffirefly-common+repo%3Ahyperledger%2Ffirefly-perf-cli+repo%3Ahyperledger%2Ffirefly-tokens-erc1155+repo%3Ahyperledger%2Ffirefly-tokens-erc20-erc721+repo%3Ahyperledger%2Ffirefly-sdk-nodejs+label%3A%22Good+first+issue%22+state%3Aopen&type=Issues&ref=advsearch&l=&l=){: .md-button .md-button--primary} > **NOTE** Hyperledger FireFly has a microservice architecture so it has many different GitHub repos. Use the link or the button above to look for "Good First Issues" across all the repos at once. Here are some other suggestions of places to get started, based on experience you may already have: ### Any level of experience + If you looking to make your first open source contribution the [FireFly documentation](https://github.com/hyperledger/firefly/tree/main/docs) is a great place to make small, easy improvements. These improvements are also very valuable, because they help the next person that may want to know the same thing. -Here are some detailed instructions on [Contributing to Documentation](./docs_setup.html) +Here are some detailed instructions on [Contributing to Documentation](./docs_setup.md) ### Go experience + If you have some experience in Go and really want to jump into FireFly, the [FireFly Core](https://github.com/hyperledger/firefly/issues) is the heart of the project. -Here are some detailed instructions on [Setting up a FireFly Core Development Environment](./dev_environment_setup.html). +Here are some detailed instructions on [Setting up a FireFly Core Development Environment](./dev_environment_setup.md). ### Little or no Go experience, but want to learn + If you don't have a lot of experience with Go, but are interested in learning, the [FireFly CLI](https://github.com/hyperledger/firefly-cli/issues) might be a good place to start. The FireFly CLI is a tool to set up local instances of FireFly for building apps that use FireFly, and for doing development on FireFly itself. ### TypeScript experience + If you have some experience in TypeScript, there are several FireFly microservices that are written in TypeScript. The [Data Exchange](https://github.com/hyperledger/firefly-dataexchange-https/issues) is used for private messaging between FireFly nodes. The [ERC-20/ERC-271 Tokens Connector](https://github.com/hyperledger/firefly-tokens-erc20-erc721/issues) and [ERC-1155 Tokens Connector](https://github.com/hyperledger/firefly-tokens-erc1155/issues) are used to abstract token contract specifics from the FireFly Core. ### React/TypeScript experience + If you want to do some frontend development, the [FireFly UI](https://github.com/hyperledger/firefly-ui/issues) is written in TypeScript and React. ### Go and blockchain experience + If you already have some experience with blockchain and want to work on some backend components, the blockchain connectors, [firefly-ethconnect](https://github.com/hyperledger/firefly-ethconnect/issues) (for Ethereum) and [firefly-fabconnect](https://github.com/hyperledger/firefly-fabconnect/issues) (for Fabric) are great places to get involved. ## πŸ“ Make changes + To contribute to the repository, please [fork the repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) that you want to change. Then clone your fork locally on your machine and make your changes. As you commit your changes, push them to your fork. More information on making commits below. ## πŸ“‘ Commit with Developer Certificate of Origin + As with all Hyperledger repositories, FireFly requires proper sign-off on every commit that is merged into the `main` branch. The sign-off indicates that you certify the changes you are submitting are in accordance with the [Developer Certificate of Origin](https://developercertificate.org/). To sign-off on your commit, you can use the `-s` flag when you commit changes. ``` @@ -83,6 +80,7 @@ This will add a string like this to the end of your commit message: > **NOTE:** [Sign-off](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt--s) is _not_ the same thing as [signing your commits](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt--Sltkeyidgt) with a private key. Both operations use a similar flag, which can be confusing. The one you want is the _lowercase_ `-s` πŸ™‚ ## πŸ“₯ Open a Pull Request + When you're ready to submit your changes for review, [open a Pull Request back to the upstream repository](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). When you open your pull request, the maintainers will automatically be notified. Additionally, a series of automated checks will be performed on your code to make sure it passes certain repository specific requirements. Maintainers may have suggestions on things to improve in your pull request. It is our goal to get code that is beneficial to the project merged as quickly as possible, so we don't like to leave pull requests hanging around for a long time. If the project maintainers are satisfied with the changes, they will approve and merge the pull request. @@ -90,6 +88,7 @@ Maintainers may have suggestions on things to improve in your pull request. It i Thanks for your interest in collaborating on this project! ## Inclusivity + The Hyperledger Foundation and the FireFly project are committed to fostering a community that is welcoming to all people. When participating in community discussions, contributing code, or documentaiton, please abide by the following guidelines: - Consider that users who will read the docs are from different background and cultures and that they have different preferences. diff --git a/docs/contributors/release_guide.md b/doc-site/docs/contributors/release_guide.md similarity index 93% rename from docs/contributors/release_guide.md rename to doc-site/docs/contributors/release_guide.md index 3d2607ab9..f14351275 100644 --- a/docs/contributors/release_guide.md +++ b/doc-site/docs/contributors/release_guide.md @@ -1,28 +1,19 @@ --- -layout: default title: Release Guide -parent: pages.contributors -nav_order: 8 --- # Release Guide -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- - This guide will walk you through creating a release. --- ## Versioning scheme -FireFly follows semantic versioning. For more details on how we determine which version to use please see the [Versioning Scheme guide](version_scheme.html). + +FireFly follows semantic versioning. For more details on how we determine which version to use please see the [Versioning Scheme guide](version_scheme.md). ## The `manifest.json` file + FireFly has a [`manifest.json` file in the root of the repo](https://github.com/hyperledger/firefly/blob/main/manifest.json). This file contains a list of versions (both tag and sha) for each of the microservices that should be used with this specific commit. If you need FireFly to use a newer version of a microservice listed in this file, you should update the `manifest.json` file, commit it, and include it in your PR. **This will trigger an end-to-end test run, using the specified versions.** Here is an example of what the `manifest.json` looks like: @@ -55,20 +46,25 @@ Here is an example of what the `manifest.json` looks like: > **NOTE**: You can run `make manifest` in the FireFly core source directory, and a script will run to automatically get the latests non-pre-release version of each of FireFly's microservices. If you need to use a snapshot or pre-release version you should edit `manifest.json` file manually, as this script will not fetch those versions. ## Creating a new release + Releases and builds are managed by GitHub. New binaries and/or Docker images will automatically be created when a new release is published. The easiest way to create a release is through the web UI for the repo that you wish to release. ### 1) Navigate to the release page for the repo + ![Releases](../images/releases.png "Releases") ### 2) Click the `Draft a new release` button + ![Draft release](../images/draft_release.png "Draft release") ### 3) Fill out the form for your release + ![Create release](../images/create_release.png "Create release") It is recommended to start with the auto-generated release notes. Additional notes can be added as-needed. ## Automatic Docker builds + After cutting a new release, a GitHub Action will automatically start a new Docker build, if the repo has a Docker image associated with it. You can check the status of the build by clicking the "Actions" tab along the top of the page, for that repo. -![GitHub Actions](../images/actions.png "GitHub Actions") \ No newline at end of file +![GitHub Actions](../images/actions.png "GitHub Actions") diff --git a/docs/contributors/version_scheme.md b/doc-site/docs/contributors/version_scheme.md similarity index 93% rename from docs/contributors/version_scheme.md rename to doc-site/docs/contributors/version_scheme.md index 0cc8ce65a..2454ac5e5 100644 --- a/docs/contributors/version_scheme.md +++ b/doc-site/docs/contributors/version_scheme.md @@ -1,20 +1,9 @@ --- -layout: default title: Versioning Scheme -parent: pages.contributors -nav_order: 7 --- # Versioning Scheme -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- - This page describes FireFly's versioning scheme --- diff --git a/docs/faqs/index.md b/doc-site/docs/faqs/index.md similarity index 91% rename from docs/faqs/index.md rename to doc-site/docs/faqs/index.md index 94b69b9d1..e1005c0f6 100644 --- a/docs/faqs/index.md +++ b/doc-site/docs/faqs/index.md @@ -1,12 +1,7 @@ --- -layout: i18n_page -title: pages.faqs -nav_order: 9 -has_children: false +title: FAQs --- -# FAQs - Find answers to the most commonly asked FireFly questions. ## How does FireFly enable multi-chain applications? @@ -19,7 +14,7 @@ There aren't any out of the box bridges to connect two separate chains together, The recommended way to deploy smart contracts on Ethereum chains is by using FireFly's built in API. For a step by step example of how to do this you can refer to the [Smart Contract Tutorial](../tutorials/custom_contracts/ethereum.md#contract-deployment) for Ethereum based chains. -For Fabric networks, please refer to the [Fabric chaincode lifecycle docs](https://hyperledger-fabric.readthedocs.io/en/latest/chaincode_lifecycle.html) for detailed instructions on how to deploy and manage Fabric chaincode. +For Fabric networks, please refer to the [Fabric chaincode lifecycle docs](https://hyperledger-fabric.readthedocs.io/en/latest/chaincode_lifecycle.md) for detailed instructions on how to deploy and manage Fabric chaincode. ## 🦊 Can I connect FireFly to MetaMask? diff --git a/docs/gettingstarted/firefly_cli.md b/doc-site/docs/gettingstarted/firefly_cli.md similarity index 73% rename from docs/gettingstarted/firefly_cli.md rename to doc-site/docs/gettingstarted/firefly_cli.md index 521a231ea..9d0073253 100644 --- a/docs/gettingstarted/firefly_cli.md +++ b/doc-site/docs/gettingstarted/firefly_cli.md @@ -1,22 +1,8 @@ --- -layout: default title: β‘  Install the FireFly CLI -parent: pages.getting_started -nav_order: 1 --- -# β‘  Install the FireFly CLI - -{: .no_toc } - -## Table of contents - -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- +# Install the FireFly CLI ## Prerequisites @@ -32,7 +18,7 @@ In order to run the FireFly CLI, you will need a few things installed on your de ### Windows Users - > **NOTE**: For Windows users, we recommend that you use [Windows Subsystem for Linux 2 (WSL2)](https://docs.microsoft.com/en-us/windows/wsl/). Binaries provided for Linux will work in this environment. +> **NOTE**: For Windows users, we recommend that you use [Windows Subsystem for Linux 2 (WSL2)](https://docs.microsoft.com/en-us/windows/wsl/). Binaries provided for Linux will work in this environment. ## Install the CLI @@ -54,7 +40,7 @@ If you downloaded the package from GitHub into a different directory, you will n ### macOSUsers - > **NOTE**: On recent versions of macOS, default security settings will prevent the FireFly CLI binary from running, because it was downloaded from the internet. You will need to [allow the FireFly CLI in System Preferences](https://github.com/hyperledger/firefly-cli/blob/main/docs/mac_help.md), before it will run. +> **NOTE**: On recent versions of macOS, default security settings will prevent the FireFly CLI binary from running, because it was downloaded from the internet. You will need to [allow the FireFly CLI in System Preferences](https://github.com/hyperledger/firefly-cli/blob/main/docs/mac_help.md), before it will run. ### Alternative installation method: Install via Go @@ -79,4 +65,4 @@ After using either installation method above, you can verify that the CLI is suc Now that you've got the FireFly CLI set up on your machine, the next step is to create and start a FireFly stack. -[β‘‘ Start your environment β†’](setup_env.md){: .btn .btn-purple .float-right .mb-5} +[β‘‘ Start your environment β†’](setup_env.md){: .md-button .md-button--primary} diff --git a/docs/gettingstarted/index.md b/doc-site/docs/gettingstarted/index.md similarity index 89% rename from docs/gettingstarted/index.md rename to doc-site/docs/gettingstarted/index.md index b342697a6..d396812a3 100644 --- a/docs/gettingstarted/index.md +++ b/doc-site/docs/gettingstarted/index.md @@ -1,12 +1,7 @@ --- -layout: i18n_page -title: pages.getting_started -nav_order: 3 -has_children: true -has_toc: false +title: Getting Started --- -# Getting Started If you're new to FireFly, this is the perfect place to start! With the FireFly CLI and the FireFly Sandbox it's really easy to get started building powerful blockchain apps. Just follow along with the steps below and you'll be up and running in no time!

@@ -16,16 +11,18 @@ If you're new to FireFly, this is the perfect place to start! With the FireFly C

- ### What you will accomplish with this guide + With this easy-to-follow guide, you'll go from "zero" to blockchain-hero in the time it takes to drink a single cup of coffee. It will walk you through setting up your machine, all the way through sending your first blockchain transactions using the FireFly Sandbox. ![FireFly Sandbox](../images/sandbox/sandbox_broadcast.png) ### We're here to help! + We want to make it as easy as possible for anyone to get started with FireFly, and we don't want anyone to feel like they're stuck. If you're having trouble, or are just curious about what else you can do with FireFly we encourage you to [join the Hyperledger Discord server](https://discord.gg/hyperledger) and come chat with us in the #firefly channel. ## Get started: Install the FireFly CLI + Now that you've got the FireFly CLI set up on your machine, the next step is to create and start a FireFly stack. -[β‘  Install the FireFly CLI β†’](firefly_cli.md){: .btn .btn-purple .float-right .mb-5} +[β‘  Install the FireFly CLI β†’](firefly_cli.md){: .md-button .md-button--primary} diff --git a/docs/gettingstarted/sandbox.md b/doc-site/docs/gettingstarted/sandbox.md similarity index 97% rename from docs/gettingstarted/sandbox.md rename to doc-site/docs/gettingstarted/sandbox.md index 8224bf5ae..6e2fe974a 100644 --- a/docs/gettingstarted/sandbox.md +++ b/doc-site/docs/gettingstarted/sandbox.md @@ -1,25 +1,14 @@ --- -layout: default title: β‘’ Use the Sandbox -parent: pages.getting_started -nav_order: 3 --- # Use the Sandbox -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- ## Previous steps: Start your environment + If you haven't started a FireFly stack already, please go back to the previous step and read the guide on how to [Start your environment](./setup_env.md). -[← β‘‘ Start your environment](setup_env.md){: .btn .btn-purple .mb-5} +[← β‘‘ Start your environment](setup_env.md){: .md-button .md-button--primary} Now that you have a full network of three Supernodes running on your machine, let's look at the first two components that you will interact with: the FireFly Sandbox and the FireFly Explorer. @@ -66,8 +55,6 @@ To see logs for your stack run: ff logs dev ``` - - ## Sandbox Layout ![Sandbox Messages](../images/sandbox/sandbox_broadcast.png) @@ -75,14 +62,17 @@ ff logs dev The Sandbox is split up into three columns: ### Left column: Prepare your request + On the left-hand side of the page, you can fill out simple form fields to construct messages and more. Some tabs have more types of requests on them in sections that can be expanded or collapsed. Across the top of this column there are three tabs that switch between the three main sets of functionality in the Sandbox. The next three sections of this guide will walk you through each one of these. The first tab we will explore is the **MESSAGING** tab. This is where we can send broadcasts and private messages. ### Middle column: Preview server code and see response + As you type in the form on the left side of the page, you may notice that the source code in the top middle of the page updates automatically. If you were building a backend app, this is an example of code that your app could use to call the FireFly SDK. The middle column also contains a `RUN` button to actually send the request. ### Right column: Events received on the WebSocket + On the right-hand side of the page you can see a stream of events being received on a WebSocket connection that the backend has open to FireFly. For example, as you make requests to send messages, you can see when the messages are asynchronously confirmed. ## Messages @@ -126,4 +116,5 @@ The Contracts section of the Sandbox lets you interact with custom smart contrac - Use the Swagger UI to call a smart contract function that emits an event. Verify that the event is received in the Sandbox and shows up in the FireFly Explorer. ## Go forth and build! + At this point you should have a pretty good understanding of some of the major features of Hyperledger FireFly. Now, using what you've learned, you can go and build your own Web3 app! Don't forget to [join the Hyperledger Discord server](https://discord.gg/hyperledger) and come chat with us in the #firefly channel. diff --git a/docs/gettingstarted/setup_env.md b/doc-site/docs/gettingstarted/setup_env.md similarity index 96% rename from docs/gettingstarted/setup_env.md rename to doc-site/docs/gettingstarted/setup_env.md index 2495cfeb6..95e7baffc 100644 --- a/docs/gettingstarted/setup_env.md +++ b/doc-site/docs/gettingstarted/setup_env.md @@ -1,25 +1,14 @@ --- -layout: default title: β‘‘ Start your environment -parent: pages.getting_started -nav_order: 2 --- # Start your environment -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- ## Previous steps: Install the FireFly CLI + If you haven't set up the FireFly CLI already, please go back to the previous step and read the guide on how to [Install the FireFly CLI](./firefly_cli.md). -[← β‘  Install the FireFly CLI](firefly_cli.md){: .btn .btn-purple .mb-5} +[← β‘  Install the FireFly CLI](firefly_cli.md){: .md-button .md-button--primary} Now that you have the FireFly CLI installed, you are ready to run some Supernodes on your machine! @@ -42,21 +31,25 @@ The FireFly stack will run in a `docker-compose` project. For systems that run D It's really easy to create a new FireFly stack. The `ff init` command can create a new stack for you, and will prompt you for a few details such as the name, and how many members you want in your stack. To create an Ethereum based stack, run: + ``` ff init ethereum ``` To create an Fabric based stack, run: + ``` ff init fabric ``` Choose a stack name. For this guide, I will choose the name `dev`, but you can pick whatever you want: + ``` stack name: dev ``` Chose the number of members for your stack. For this guide, we should pick `3` members, so we can try out both public and private messaging use cases: + ``` number of members: 3 ``` @@ -65,7 +58,7 @@ number of members: 3 ### Stack initialization options -There are quite a few options that you can choose from when creating a new stack. For now, we'll just stick with the defaults. To see the full list of Ethereum options, just run `ff init ethereum --help` or to see the full list of Fabric options run `ff init fabric --help` +There are quite a few options that you can choose from when creating a new stack. For now, we'll just stick with the defaults. To see the full list of Ethereum options, just run `ff init ethereum --help` or to see the full list of Fabric options run `ff init fabric --help` ``` ff init ethereum --help @@ -150,6 +143,7 @@ ff logs dev ``` ## Next steps: Use in the Sandbox + Now that you have some Supernodes running, it's time to start playing: in the Sandbox! -[β‘’ Use the Sandbox β†’](sandbox.md){: .btn .btn-purple .float-right .mb-5} \ No newline at end of file +[β‘’ Use the Sandbox β†’](sandbox.md){: .md-button .md-button--primary} diff --git a/docs/images/metamask/account_address.png b/doc-site/docs/images/account_address.png similarity index 100% rename from docs/images/metamask/account_address.png rename to doc-site/docs/images/account_address.png diff --git a/docs/images/actions.png b/doc-site/docs/images/actions.png similarity index 100% rename from docs/images/actions.png rename to doc-site/docs/images/actions.png diff --git a/docs/images/metamask/add_network.png b/doc-site/docs/images/add_network.png similarity index 100% rename from docs/images/metamask/add_network.png rename to doc-site/docs/images/add_network.png diff --git a/docs/images/asset_transfer_swagger.png b/doc-site/docs/images/asset_transfer_swagger.png similarity index 100% rename from docs/images/asset_transfer_swagger.png rename to doc-site/docs/images/asset_transfer_swagger.png diff --git a/docs/images/blockchain-sub-status.png b/doc-site/docs/images/blockchain-sub-status.png similarity index 100% rename from docs/images/blockchain-sub-status.png rename to doc-site/docs/images/blockchain-sub-status.png diff --git a/docs/images/metamask/contract_address.png b/doc-site/docs/images/contract_address.png similarity index 100% rename from docs/images/metamask/contract_address.png rename to doc-site/docs/images/contract_address.png diff --git a/docs/images/create_release.png b/doc-site/docs/images/create_release.png similarity index 100% rename from docs/images/create_release.png rename to doc-site/docs/images/create_release.png diff --git a/docs/images/define_a_datatype.png b/doc-site/docs/images/define_a_datatype.png similarity index 100% rename from docs/images/define_a_datatype.png rename to doc-site/docs/images/define_a_datatype.png diff --git a/docs/images/docker_memory.png b/doc-site/docs/images/docker_memory.png similarity index 100% rename from docs/images/docker_memory.png rename to doc-site/docs/images/docker_memory.png diff --git a/docs/images/draft_release.png b/doc-site/docs/images/draft_release.png similarity index 100% rename from docs/images/draft_release.png rename to doc-site/docs/images/draft_release.png diff --git a/docs/images/event_driven_programming_model.jpg b/doc-site/docs/images/event_driven_programming_model.jpg similarity index 100% rename from docs/images/event_driven_programming_model.jpg rename to doc-site/docs/images/event_driven_programming_model.jpg diff --git a/docs/images/ff_start.gif b/doc-site/docs/images/ff_start.gif similarity index 100% rename from docs/images/ff_start.gif rename to doc-site/docs/images/ff_start.gif diff --git a/docs/images/firefly-getting-started-steps.png b/doc-site/docs/images/firefly-getting-started-steps.png similarity index 100% rename from docs/images/firefly-getting-started-steps.png rename to doc-site/docs/images/firefly-getting-started-steps.png diff --git a/docs/images/firefly_architecture_overview.jpg b/doc-site/docs/images/firefly_architecture_overview.jpg similarity index 100% rename from docs/images/firefly_architecture_overview.jpg rename to doc-site/docs/images/firefly_architecture_overview.jpg diff --git a/docs/images/firefly_blockchain_connector_framework.png b/doc-site/docs/images/firefly_blockchain_connector_framework.png similarity index 100% rename from docs/images/firefly_blockchain_connector_framework.png rename to doc-site/docs/images/firefly_blockchain_connector_framework.png diff --git a/docs/images/firefly_cli.png b/doc-site/docs/images/firefly_cli.png similarity index 100% rename from docs/images/firefly_cli.png rename to doc-site/docs/images/firefly_cli.png diff --git a/docs/images/firefly_connector_toolkit_event_streams.jpg b/doc-site/docs/images/firefly_connector_toolkit_event_streams.jpg similarity index 100% rename from docs/images/firefly_connector_toolkit_event_streams.jpg rename to doc-site/docs/images/firefly_connector_toolkit_event_streams.jpg diff --git a/docs/images/firefly_core.png b/doc-site/docs/images/firefly_core.png similarity index 100% rename from docs/images/firefly_core.png rename to doc-site/docs/images/firefly_core.png diff --git a/docs/images/firefly_data_privacy_model.jpg b/doc-site/docs/images/firefly_data_privacy_model.jpg similarity index 100% rename from docs/images/firefly_data_privacy_model.jpg rename to doc-site/docs/images/firefly_data_privacy_model.jpg diff --git a/docs/images/firefly_data_transport_layers.png b/doc-site/docs/images/firefly_data_transport_layers.png similarity index 100% rename from docs/images/firefly_data_transport_layers.png rename to doc-site/docs/images/firefly_data_transport_layers.png diff --git a/docs/images/firefly_event_bus.jpg b/doc-site/docs/images/firefly_event_bus.jpg similarity index 100% rename from docs/images/firefly_event_bus.jpg rename to doc-site/docs/images/firefly_event_bus.jpg diff --git a/docs/images/firefly_event_model.jpg b/doc-site/docs/images/firefly_event_model.jpg similarity index 100% rename from docs/images/firefly_event_model.jpg rename to doc-site/docs/images/firefly_event_model.jpg diff --git a/docs/images/firefly_event_subscription_model.jpg b/doc-site/docs/images/firefly_event_subscription_model.jpg similarity index 100% rename from docs/images/firefly_event_subscription_model.jpg rename to doc-site/docs/images/firefly_event_subscription_model.jpg diff --git a/docs/images/firefly_explorer.png b/doc-site/docs/images/firefly_explorer.png similarity index 100% rename from docs/images/firefly_explorer.png rename to doc-site/docs/images/firefly_explorer.png diff --git a/docs/images/firefly_first_successful_transaction.png b/doc-site/docs/images/firefly_first_successful_transaction.png similarity index 100% rename from docs/images/firefly_first_successful_transaction.png rename to doc-site/docs/images/firefly_first_successful_transaction.png diff --git a/docs/images/firefly_functionality_overview.png b/doc-site/docs/images/firefly_functionality_overview.png similarity index 100% rename from docs/images/firefly_functionality_overview.png rename to doc-site/docs/images/firefly_functionality_overview.png diff --git a/docs/images/firefly_functionality_overview_apps.png b/doc-site/docs/images/firefly_functionality_overview_apps.png similarity index 100% rename from docs/images/firefly_functionality_overview_apps.png rename to doc-site/docs/images/firefly_functionality_overview_apps.png diff --git a/docs/images/firefly_functionality_overview_connectivity.png b/doc-site/docs/images/firefly_functionality_overview_connectivity.png similarity index 100% rename from docs/images/firefly_functionality_overview_connectivity.png rename to doc-site/docs/images/firefly_functionality_overview_connectivity.png diff --git a/docs/images/firefly_functionality_overview_digital_assets.png b/doc-site/docs/images/firefly_functionality_overview_digital_assets.png similarity index 100% rename from docs/images/firefly_functionality_overview_digital_assets.png rename to doc-site/docs/images/firefly_functionality_overview_digital_assets.png diff --git a/docs/images/firefly_functionality_overview_flows.png b/doc-site/docs/images/firefly_functionality_overview_flows.png similarity index 100% rename from docs/images/firefly_functionality_overview_flows.png rename to doc-site/docs/images/firefly_functionality_overview_flows.png diff --git a/docs/images/firefly_functionality_overview_orchestration_engine.png b/doc-site/docs/images/firefly_functionality_overview_orchestration_engine.png similarity index 100% rename from docs/images/firefly_functionality_overview_orchestration_engine.png rename to doc-site/docs/images/firefly_functionality_overview_orchestration_engine.png diff --git a/docs/images/firefly_functionality_overview_security.png b/doc-site/docs/images/firefly_functionality_overview_security.png similarity index 100% rename from docs/images/firefly_functionality_overview_security.png rename to doc-site/docs/images/firefly_functionality_overview_security.png diff --git a/docs/images/firefly_functionality_overview_tools.png b/doc-site/docs/images/firefly_functionality_overview_tools.png similarity index 100% rename from docs/images/firefly_functionality_overview_tools.png rename to doc-site/docs/images/firefly_functionality_overview_tools.png diff --git a/docs/images/firefly_intro_overview.png b/doc-site/docs/images/firefly_intro_overview.png similarity index 100% rename from docs/images/firefly_intro_overview.png rename to doc-site/docs/images/firefly_intro_overview.png diff --git a/docs/images/firefly_node.png b/doc-site/docs/images/firefly_node.png similarity index 100% rename from docs/images/firefly_node.png rename to doc-site/docs/images/firefly_node.png diff --git a/docs/images/firefly_orchestration_engine.png b/doc-site/docs/images/firefly_orchestration_engine.png similarity index 100% rename from docs/images/firefly_orchestration_engine.png rename to doc-site/docs/images/firefly_orchestration_engine.png diff --git a/docs/images/firefly_plugin_architecture.jpg b/doc-site/docs/images/firefly_plugin_architecture.jpg similarity index 100% rename from docs/images/firefly_plugin_architecture.jpg rename to doc-site/docs/images/firefly_plugin_architecture.jpg diff --git a/docs/images/firefly_plugin_architecture.svg b/doc-site/docs/images/firefly_plugin_architecture.svg similarity index 100% rename from docs/images/firefly_plugin_architecture.svg rename to doc-site/docs/images/firefly_plugin_architecture.svg diff --git a/docs/images/firefly_stack.svg b/doc-site/docs/images/firefly_stack.svg similarity index 100% rename from docs/images/firefly_stack.svg rename to doc-site/docs/images/firefly_stack.svg diff --git a/docs/images/firefly_transaction_manager.jpg b/doc-site/docs/images/firefly_transaction_manager.jpg similarity index 100% rename from docs/images/firefly_transaction_manager.jpg rename to doc-site/docs/images/firefly_transaction_manager.jpg diff --git a/docs/images/firefly_transactions_explorer_view.png b/doc-site/docs/images/firefly_transactions_explorer_view.png similarity index 100% rename from docs/images/firefly_transactions_explorer_view.png rename to doc-site/docs/images/firefly_transactions_explorer_view.png diff --git a/docs/images/gateway_mode.png b/doc-site/docs/images/gateway_mode.png similarity index 100% rename from docs/images/gateway_mode.png rename to doc-site/docs/images/gateway_mode.png diff --git a/docs/images/gateway_multiparty_mode.png b/doc-site/docs/images/gateway_multiparty_mode.png similarity index 100% rename from docs/images/gateway_multiparty_mode.png rename to doc-site/docs/images/gateway_multiparty_mode.png diff --git a/docs/images/getting-started-overview.png b/doc-site/docs/images/getting-started-overview.png similarity index 100% rename from docs/images/getting-started-overview.png rename to doc-site/docs/images/getting-started-overview.png diff --git a/docs/images/global_sequencing.svg b/doc-site/docs/images/global_sequencing.svg similarity index 100% rename from docs/images/global_sequencing.svg rename to doc-site/docs/images/global_sequencing.svg diff --git a/docs/images/hyperledger-firefly-namespaces-example-with-org.png b/doc-site/docs/images/hyperledger-firefly-namespaces-example-with-org.png similarity index 100% rename from docs/images/hyperledger-firefly-namespaces-example-with-org.png rename to doc-site/docs/images/hyperledger-firefly-namespaces-example-with-org.png diff --git a/docs/images/hyperledger-firefly_color.svg b/doc-site/docs/images/hyperledger-firefly_color.svg similarity index 100% rename from docs/images/hyperledger-firefly_color.svg rename to doc-site/docs/images/hyperledger-firefly_color.svg diff --git a/docs/images/hyperledger_firefly_social.png b/doc-site/docs/images/hyperledger_firefly_social.png similarity index 100% rename from docs/images/hyperledger_firefly_social.png rename to doc-site/docs/images/hyperledger_firefly_social.png diff --git a/docs/images/idempotency_keys_architecture.jpg b/doc-site/docs/images/idempotency_keys_architecture.jpg similarity index 100% rename from docs/images/idempotency_keys_architecture.jpg rename to doc-site/docs/images/idempotency_keys_architecture.jpg diff --git a/docs/images/metamask/import_tokens.png b/doc-site/docs/images/import_tokens.png similarity index 100% rename from docs/images/metamask/import_tokens.png rename to doc-site/docs/images/import_tokens.png diff --git a/docs/images/internal_event_sequencing.jpg b/doc-site/docs/images/internal_event_sequencing.jpg similarity index 100% rename from docs/images/internal_event_sequencing.jpg rename to doc-site/docs/images/internal_event_sequencing.jpg diff --git a/docs/images/intro_to_firefly.png b/doc-site/docs/images/intro_to_firefly.png similarity index 100% rename from docs/images/intro_to_firefly.png rename to doc-site/docs/images/intro_to_firefly.png diff --git a/docs/images/launch_config.png b/doc-site/docs/images/launch_config.png similarity index 100% rename from docs/images/launch_config.png rename to doc-site/docs/images/launch_config.png diff --git a/docs/images/message_broadcast_initial.png b/doc-site/docs/images/message_broadcast_initial.png similarity index 100% rename from docs/images/message_broadcast_initial.png rename to doc-site/docs/images/message_broadcast_initial.png diff --git a/docs/images/message_broadcast_sample_result.png b/doc-site/docs/images/message_broadcast_sample_result.png similarity index 100% rename from docs/images/message_broadcast_sample_result.png rename to doc-site/docs/images/message_broadcast_sample_result.png diff --git a/docs/images/message_private_broadcast.png b/doc-site/docs/images/message_private_broadcast.png similarity index 100% rename from docs/images/message_private_broadcast.png rename to doc-site/docs/images/message_private_broadcast.png diff --git a/doc-site/docs/images/metamask/account_address.png b/doc-site/docs/images/metamask/account_address.png new file mode 100644 index 000000000..6837b6742 Binary files /dev/null and b/doc-site/docs/images/metamask/account_address.png differ diff --git a/doc-site/docs/images/metamask/add_network.png b/doc-site/docs/images/metamask/add_network.png new file mode 100644 index 000000000..b6db864ee Binary files /dev/null and b/doc-site/docs/images/metamask/add_network.png differ diff --git a/doc-site/docs/images/metamask/contract_address.png b/doc-site/docs/images/metamask/contract_address.png new file mode 100644 index 000000000..ec8852c38 Binary files /dev/null and b/doc-site/docs/images/metamask/contract_address.png differ diff --git a/doc-site/docs/images/metamask/import_tokens.png b/doc-site/docs/images/metamask/import_tokens.png new file mode 100644 index 000000000..985f43161 Binary files /dev/null and b/doc-site/docs/images/metamask/import_tokens.png differ diff --git a/docs/images/metamask/network_details.png b/doc-site/docs/images/metamask/network_details.png similarity index 100% rename from docs/images/metamask/network_details.png rename to doc-site/docs/images/metamask/network_details.png diff --git a/docs/images/metamask/nft_contract_address.png b/doc-site/docs/images/metamask/nft_contract_address.png similarity index 100% rename from docs/images/metamask/nft_contract_address.png rename to doc-site/docs/images/metamask/nft_contract_address.png diff --git a/docs/images/metamask/nft_token_balance.png b/doc-site/docs/images/metamask/nft_token_balance.png similarity index 100% rename from docs/images/metamask/nft_token_balance.png rename to doc-site/docs/images/metamask/nft_token_balance.png diff --git a/docs/images/metamask/send_tokens.png b/doc-site/docs/images/metamask/send_tokens.png similarity index 100% rename from docs/images/metamask/send_tokens.png rename to doc-site/docs/images/metamask/send_tokens.png diff --git a/docs/images/metamask/settings.png b/doc-site/docs/images/metamask/settings.png similarity index 100% rename from docs/images/metamask/settings.png rename to doc-site/docs/images/metamask/settings.png diff --git a/docs/images/metamask/tokens_received.png b/doc-site/docs/images/metamask/tokens_received.png similarity index 100% rename from docs/images/metamask/tokens_received.png rename to doc-site/docs/images/metamask/tokens_received.png diff --git a/docs/images/multi_protocol.png b/doc-site/docs/images/multi_protocol.png similarity index 100% rename from docs/images/multi_protocol.png rename to doc-site/docs/images/multi_protocol.png diff --git a/docs/images/multiparty_business_process_flow.jpg b/doc-site/docs/images/multiparty_business_process_flow.jpg similarity index 100% rename from docs/images/multiparty_business_process_flow.jpg rename to doc-site/docs/images/multiparty_business_process_flow.jpg diff --git a/docs/images/multiparty_mode.png b/doc-site/docs/images/multiparty_mode.png similarity index 100% rename from docs/images/multiparty_mode.png rename to doc-site/docs/images/multiparty_mode.png diff --git a/docs/images/multiparty_system1.png b/doc-site/docs/images/multiparty_system1.png similarity index 100% rename from docs/images/multiparty_system1.png rename to doc-site/docs/images/multiparty_system1.png diff --git a/doc-site/docs/images/network_details.png b/doc-site/docs/images/network_details.png new file mode 100644 index 000000000..64f29e772 Binary files /dev/null and b/doc-site/docs/images/network_details.png differ diff --git a/docs/images/new_message_view.png b/doc-site/docs/images/new_message_view.png similarity index 100% rename from docs/images/new_message_view.png rename to doc-site/docs/images/new_message_view.png diff --git a/doc-site/docs/images/nft_contract_address.png b/doc-site/docs/images/nft_contract_address.png new file mode 100644 index 000000000..2482ea172 Binary files /dev/null and b/doc-site/docs/images/nft_contract_address.png differ diff --git a/doc-site/docs/images/nft_token_balance.png b/doc-site/docs/images/nft_token_balance.png new file mode 100644 index 000000000..70e08cb43 Binary files /dev/null and b/doc-site/docs/images/nft_token_balance.png differ diff --git a/docs/images/operations_by_transaction_type.jpg b/doc-site/docs/images/operations_by_transaction_type.jpg similarity index 100% rename from docs/images/operations_by_transaction_type.jpg rename to doc-site/docs/images/operations_by_transaction_type.jpg diff --git a/docs/images/ping_pong.jpg b/doc-site/docs/images/ping_pong.jpg similarity index 100% rename from docs/images/ping_pong.jpg rename to doc-site/docs/images/ping_pong.jpg diff --git a/docs/images/ping_pong.svg b/doc-site/docs/images/ping_pong.svg similarity index 100% rename from docs/images/ping_pong.svg rename to doc-site/docs/images/ping_pong.svg diff --git a/docs/images/problem_statement.png b/doc-site/docs/images/problem_statement.png similarity index 100% rename from docs/images/problem_statement.png rename to doc-site/docs/images/problem_statement.png diff --git a/docs/images/releases.png b/doc-site/docs/images/releases.png similarity index 100% rename from docs/images/releases.png rename to doc-site/docs/images/releases.png diff --git a/docs/images/sandbox/sandbox_api_swagger.png b/doc-site/docs/images/sandbox/sandbox_api_swagger.png similarity index 100% rename from docs/images/sandbox/sandbox_api_swagger.png rename to doc-site/docs/images/sandbox/sandbox_api_swagger.png diff --git a/docs/images/sandbox/sandbox_broadcast.png b/doc-site/docs/images/sandbox/sandbox_broadcast.png similarity index 100% rename from docs/images/sandbox/sandbox_broadcast.png rename to doc-site/docs/images/sandbox/sandbox_broadcast.png diff --git a/docs/images/sandbox/sandbox_broadcast_result.png b/doc-site/docs/images/sandbox/sandbox_broadcast_result.png similarity index 100% rename from docs/images/sandbox/sandbox_broadcast_result.png rename to doc-site/docs/images/sandbox/sandbox_broadcast_result.png diff --git a/docs/images/sandbox/sandbox_contracts_api.png b/doc-site/docs/images/sandbox/sandbox_contracts_api.png similarity index 100% rename from docs/images/sandbox/sandbox_contracts_api.png rename to doc-site/docs/images/sandbox/sandbox_contracts_api.png diff --git a/docs/images/sandbox/sandbox_token_pool.png b/doc-site/docs/images/sandbox/sandbox_token_pool.png similarity index 100% rename from docs/images/sandbox/sandbox_token_pool.png rename to doc-site/docs/images/sandbox/sandbox_token_pool.png diff --git a/docs/images/sandbox/sandbox_token_transfer_result.png b/doc-site/docs/images/sandbox/sandbox_token_transfer_result.png similarity index 100% rename from docs/images/sandbox/sandbox_token_transfer_result.png rename to doc-site/docs/images/sandbox/sandbox_token_transfer_result.png diff --git a/doc-site/docs/images/send_tokens.png b/doc-site/docs/images/send_tokens.png new file mode 100644 index 000000000..35910a534 Binary files /dev/null and b/doc-site/docs/images/send_tokens.png differ diff --git a/doc-site/docs/images/settings.png b/doc-site/docs/images/settings.png new file mode 100644 index 000000000..c8408a05a Binary files /dev/null and b/doc-site/docs/images/settings.png differ diff --git a/docs/images/simple_storage_swagger.png b/doc-site/docs/images/simple_storage_swagger.png similarity index 100% rename from docs/images/simple_storage_swagger.png rename to doc-site/docs/images/simple_storage_swagger.png diff --git a/docs/images/smart_contracts_async_flow.svg b/doc-site/docs/images/smart_contracts_async_flow.svg similarity index 100% rename from docs/images/smart_contracts_async_flow.svg rename to doc-site/docs/images/smart_contracts_async_flow.svg diff --git a/doc-site/docs/images/tokens_received.png b/doc-site/docs/images/tokens_received.png new file mode 100644 index 000000000..0d40f110e Binary files /dev/null and b/doc-site/docs/images/tokens_received.png differ diff --git a/docs/images/understanding_firefly1.png b/doc-site/docs/images/understanding_firefly1.png similarity index 100% rename from docs/images/understanding_firefly1.png rename to doc-site/docs/images/understanding_firefly1.png diff --git a/docs/images/websocket_example.png b/doc-site/docs/images/websocket_example.png similarity index 100% rename from docs/images/websocket_example.png rename to doc-site/docs/images/websocket_example.png diff --git a/docs/_i18n/en/index.md b/doc-site/docs/index.md similarity index 77% rename from docs/_i18n/en/index.md rename to doc-site/docs/index.md index 1c5e2602c..d41d9f3e7 100644 --- a/docs/_i18n/en/index.md +++ b/doc-site/docs/index.md @@ -2,13 +2,13 @@ ![Hyperledger FireFly](./images/hyperledger_firefly_social.png) -Hyperledger FireFly is an [open source Supernode](./overview/supernode_concept.html), a complete stack for enterprises to build and scale secure Web3 applications. +Hyperledger FireFly is an [open source Supernode](./overview/supernode_concept.md), a complete stack for enterprises to build and scale secure Web3 applications. The easiest way to understand a FireFly Supernode is to think of it like a toolbox. Connect your existing apps and/or back office systems to the toolbox and within it there are two different sets of tools. One set of tools helps you connect to the Web3 world that already exists, and the other set allows you to build new decentralized applications quickly with security and scalability. -Head to the [Understanding FireFly](./overview/supernode_concept.html) section for more details. +Head to the [Understanding FireFly](./overview/supernode_concept.md) section for more details. -## Table of contents +## Documentation Sections - [Understanding FireFly](./overview/) - [Getting Started](./gettingstarted/) @@ -16,5 +16,6 @@ Head to the [Understanding FireFly](./overview/supernode_concept.html) section f - [Reference](./reference/) - [Architecture](./architecture/) - [Contributors](./contributors/) -- [API Spec](./swagger/swagger.html) -- [FAQs](./faqs/) \ No newline at end of file +- [API Spec](./swagger/) +- [FAQs](./faqs/) +- [Release notes](./release_notes/) diff --git a/docs/overview/gateway_features.md b/doc-site/docs/overview/gateway_features.md similarity index 93% rename from docs/overview/gateway_features.md rename to doc-site/docs/overview/gateway_features.md index 356688273..8d9bc1f2e 100644 --- a/docs/overview/gateway_features.md +++ b/doc-site/docs/overview/gateway_features.md @@ -1,19 +1,5 @@ --- -layout: i18n_page -title: pages.web3_gateway_features -parent: pages.understanding_firefly -nav_order: 4 ---- - -# Web3 Gateway Features -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - +title: Web3 Gateway Features --- Web3 Gateway features allow your FireFly Supernode to connect to any blockchain ecosystem, public or private. When a chain is connected, the FireFly Supernode may invoke custom smart contracts, interact with tokens, and monitor transactions. A single FireFly Supernode is able to have multiple namespaces, or isolated environments, where each namespace is a connection to a different chain. @@ -28,9 +14,9 @@ token economies, in multiple blockchains, using the same infrastructure and sign The complexities of how each token works, and how each blockchain works, are abstracted away from you by the Hyperledger FireFly [Connector Framework](./key_components/connectors.md). -All of the layers of plumbing required to execute a transaction exactly once on a -blockchain, and tracking it through to completion, are part of the stack. Deploy and -configure them once in your Web3 gateway, and use them for multiple use cases in your +All of the layers of plumbing required to execute a transaction exactly once on a +blockchain, and tracking it through to completion, are part of the stack. Deploy and +configure them once in your Web3 gateway, and use them for multiple use cases in your enterprise. ## Invoke any other type of smart contract @@ -45,7 +31,7 @@ The same reliable transaction submission framework is used as for token transfer and you can use Hyperledger FireFly as a high volume staging post for those transactions. - Handles peaks in workload, drip-feeding transactions onto the chain -- Handles large batch submissions, tracking +- Handles large batch submissions, tracking - Manages nonce assignment at high volume - Idempotent APIs assuring that business transactions are submitted exactly once @@ -91,7 +77,7 @@ This means the integration into your application and core systems needs to be ev The same features that support reliable indexing of the blockchain data, allow reliable triggering of application code, business workflows, and core system integrations. -> Learn more about the [FireFly Event Bus](../reference/events.html) +> Learn more about the [FireFly Event Bus](../reference/events.md) ## Manage decentralized data (NFTs etc.) @@ -129,4 +115,4 @@ You can associate profile information with the identities, for example correlati to the identifiers in your own core systems - such as an Identity and Access Management (IAM) system, or Know Your Customer (KYC) database. -> Learn more about [Hyperledger FireFly Identities](../reference/identities.html) +> Learn more about [Hyperledger FireFly Identities](../reference/identities.md) diff --git a/docs/overview/key_components/apps.md b/doc-site/docs/overview/key_components/apps.md similarity index 94% rename from docs/overview/key_components/apps.md rename to doc-site/docs/overview/key_components/apps.md index 4be5c79df..e75413da7 100644 --- a/docs/overview/key_components/apps.md +++ b/doc-site/docs/overview/key_components/apps.md @@ -1,14 +1,5 @@ --- -layout: i18n_page -title: pages.apps -parent: pages.key_features -grand_parent: pages.understanding_firefly -nav_order: 1 ---- - -# Apps -{: .no_toc } - +title: Apps --- ![Hyperledger FireFly App Features](../../images/firefly_functionality_overview_apps.png) @@ -59,7 +50,7 @@ This means great event support is a must: - At-least-once delivery assurance, with simple instructions at the application layer > Learn all about the Hyperledger FireFly **Event Bus**, and **event-driven application architecture**, -> in [this reference section](../../reference/events.html) +> in [this reference section](../../reference/events.md) ### API Generation @@ -82,4 +73,3 @@ This means Hyperledger FireFly provides: - Generating the interface for methods and events on your smart contract - Providing robust transaction submission, and event streaming - Publishing the API, version, and location, of your smart contracts to the network - diff --git a/docs/overview/key_components/connectors.md b/doc-site/docs/overview/key_components/connectors.md similarity index 85% rename from docs/overview/key_components/connectors.md rename to doc-site/docs/overview/key_components/connectors.md index 78f0a7405..0945c349b 100644 --- a/docs/overview/key_components/connectors.md +++ b/doc-site/docs/overview/key_components/connectors.md @@ -1,15 +1,5 @@ --- -layout: i18n_page -title: pages.connector_framework -parent: pages.key_features -grand_parent: pages.understanding_firefly -nav_order: 3 ---- - -# Connector Framework - -{: .no_toc } - +title: Connector Framework --- ![Hyperledger FireFly Connectivity Features](../../images/firefly_functionality_overview_connectivity.png) @@ -32,7 +22,7 @@ to remote runtimes implemented in a variety of programming languages. - Identity - flexibility for resolving identities via Decentralized IDentifier (DID) - Persistence - the local private database -> Learn more about the [plugin architecture here](../../architecture/plugin_architecture.html) +> Learn more about the [plugin architecture here](../../architecture/plugin_architecture.md) ## Blockchain Connector Framework @@ -42,8 +32,8 @@ are provided to support the programming models, and behaviors of different block This framework has been proven with technologies as different as EVM based Layer 2 Ethereum Scaling solutions like Polygon, all the way to permissioned Hyperledger Fabric networks. -> Check out instructions to connect to a list of remote blockchain networks [here](../../tutorials/chains/). +> Check out instructions to connect to a list of remote blockchain networks [here](../../tutorials/chains/index.md). ![FireFly Blockchain Connector Framework](../../images/firefly_blockchain_connector_framework.png) -Find out more about the Blockchain Connector Framework [here](../../architecture/blockchain_connector_framework.html). \ No newline at end of file +Find out more about the Blockchain Connector Framework [here](../../architecture/blockchain_connector_framework.md). diff --git a/docs/overview/key_components/digital_assets.md b/doc-site/docs/overview/key_components/digital_assets.md similarity index 93% rename from docs/overview/key_components/digital_assets.md rename to doc-site/docs/overview/key_components/digital_assets.md index 29d052edf..d6d6931e9 100644 --- a/docs/overview/key_components/digital_assets.md +++ b/doc-site/docs/overview/key_components/digital_assets.md @@ -1,14 +1,5 @@ --- -layout: i18n_page -title: pages.digital_assets -parent: pages.key_features -grand_parent: pages.understanding_firefly -nav_order: 2 ---- - -# Digital Assets -{: .no_toc } - +title: Digital Assets --- ![Hyperledger FireFly Digital Asset Features](../../images/firefly_functionality_overview_digital_assets.png) @@ -38,7 +29,7 @@ asset ecosystem can be exposed and enforced. Whether tokens are fungible, non-fungible, or some hybrid in between. > Learn more about token standards for fungible tokens, and non-fungible -> tokens (NFTs) in [this set of tutorials](../../tutorials/tokens/) +> tokens (NFTs) in [this set of tutorials](../../tutorials/tokens/index.md) ### Transfer history / audit trail diff --git a/docs/overview/key_components/flows.md b/doc-site/docs/overview/key_components/flows.md similarity index 96% rename from docs/overview/key_components/flows.md rename to doc-site/docs/overview/key_components/flows.md index 9bae2d37d..72196640f 100644 --- a/docs/overview/key_components/flows.md +++ b/doc-site/docs/overview/key_components/flows.md @@ -1,14 +1,5 @@ --- -layout: i18n_page -title: pages.flows -parent: pages.key_features -grand_parent: pages.understanding_firefly -nav_order: 5 ---- - -# Flows -{: .no_toc } - +title: Flows --- ![Hyperledger FireFly Data Flow Features](../../images/firefly_functionality_overview_flows.png) @@ -94,5 +85,4 @@ build sophisticated transaction flows together, massively simplifying the applic ![Multi-party business process flow](../../images/multiparty_business_process_flow.jpg) -> Learn more in [Multiparty Process Flows](../multiparty/multiparty_flow.html) - +> Learn more in [Multiparty Process Flows](../multiparty/multiparty_flow.md) diff --git a/doc-site/docs/overview/key_components/index.md b/doc-site/docs/overview/key_components/index.md new file mode 100644 index 000000000..acb151a17 --- /dev/null +++ b/doc-site/docs/overview/key_components/index.md @@ -0,0 +1,8 @@ +--- +title: Key Features +--- + +![Hyperledger FireFly features](../../images/firefly_functionality_overview.png) + +Hyperledger FireFly provides a rich suite of features for building new applications, and connecting +existing Web3 ecosystems to your business. In this section we introduce each core pillar of functionality. diff --git a/docs/overview/key_components/orchestration_engine.md b/doc-site/docs/overview/key_components/orchestration_engine.md similarity index 90% rename from docs/overview/key_components/orchestration_engine.md rename to doc-site/docs/overview/key_components/orchestration_engine.md index 4474ffd80..67d52ec32 100644 --- a/docs/overview/key_components/orchestration_engine.md +++ b/doc-site/docs/overview/key_components/orchestration_engine.md @@ -1,15 +1,5 @@ --- -layout: i18n_page -title: pages.orchestration_engine -parent: pages.key_features -grand_parent: pages.understanding_firefly -nav_order: 4 ---- - -# Orchestration Engine - -{: .no_toc } - +title: Orchestration Engine --- ![Hyperledger FireFly Orchestration Engine](../../images/firefly_functionality_overview_orchestration_engine.png) @@ -53,4 +43,4 @@ core systems. ![Hyperledger FireFly Event Mode](../../images/firefly_event_model.jpg) > Learn more about the event bus and event-driven programming in this -> [reference document](http://localhost:4000/firefly/reference/events.html) \ No newline at end of file +> [reference document](http://localhost:4000/firefly/reference/events.html) diff --git a/docs/overview/key_components/security.md b/doc-site/docs/overview/key_components/security.md similarity index 83% rename from docs/overview/key_components/security.md rename to doc-site/docs/overview/key_components/security.md index 6a70accd3..50143de47 100644 --- a/docs/overview/key_components/security.md +++ b/doc-site/docs/overview/key_components/security.md @@ -1,14 +1,5 @@ --- -layout: i18n_page -title: pages.security -parent: pages.key_features -grand_parent: pages.understanding_firefly -nav_order: 6 ---- - -# Security -{: .no_toc } - +title: Security --- ![Hyperledger FireFly Security Features](../../images/firefly_functionality_overview_security.png) @@ -17,14 +8,14 @@ nav_order: 6 Hyperledger FireFly provides a pluggable infrastructure for authenticating API requests. -Each [namespace](../../reference/namespaces.html) can be configured with a different authentication +Each [namespace](../../reference/namespaces.md) can be configured with a different authentication plugin, such that different teams can have different access to resources on the same FireFly server. A reference plugin implementation is provided for HTTP Basic Auth, combined with a `htpasswd` verification of passwords with a `bcrypt` encoding. -[See this config section for details](../../reference/config.html#pluginsauth), and the +[See this config section for details](../../reference/config.md#pluginsauth), and the reference implementation [in Github](https://github.com/hyperledger/firefly-common/blob/main/pkg/auth/basic/basic_auth.go) @@ -33,7 +24,7 @@ reference implementation ## Data Partitioning and Tenancy -[Namespaces](../../reference/namespaces.html) also provide a data isolation system for different +[Namespaces](../../reference/namespaces.md) also provide a data isolation system for different applications / teams / tenants sharing a Hyperledger FireFly node. ![Namespaces](../../images/hyperledger-firefly-namespaces-example-with-org.png) diff --git a/docs/overview/key_components/tools.md b/doc-site/docs/overview/key_components/tools.md similarity index 92% rename from docs/overview/key_components/tools.md rename to doc-site/docs/overview/key_components/tools.md index cfa86a132..e313aea87 100644 --- a/docs/overview/key_components/tools.md +++ b/doc-site/docs/overview/key_components/tools.md @@ -1,15 +1,5 @@ --- -layout: i18n_page -title: pages.tools -parent: pages.key_features -grand_parent: pages.understanding_firefly -nav_order: 7 ---- - -# Tools - -{: .no_toc } - +title: Tools --- ![Hyperledger FireFly Tools](../../images/firefly_functionality_overview_tools.png) diff --git a/docs/overview/multiparty/broadcast.md b/doc-site/docs/overview/multiparty/broadcast.md similarity index 85% rename from docs/overview/multiparty/broadcast.md rename to doc-site/docs/overview/multiparty/broadcast.md index 510ffe711..1a159140b 100644 --- a/docs/overview/multiparty/broadcast.md +++ b/doc-site/docs/overview/multiparty/broadcast.md @@ -1,14 +1,5 @@ --- -layout: i18n_page -title: pages.broadcast_data -parent: pages.multiparty_features -grand_parent: pages.understanding_firefly -nav_order: 3 ---- - -# Broadcast / shared data -{: .no_toc } - +title: Broadcast / shared data --- ## Introduction @@ -31,7 +22,7 @@ which allows them to be processed by each member in a way that allows them to derive the same result - even though the processing logic on the events themselves is being performed independently by each member. -For more information see [Multiparty Event Sequencing](../../architecture/multiparty_event_sequencing.html). +For more information see [Multiparty Event Sequencing](../../architecture/multiparty_event_sequencing.md). ## Shared data @@ -60,11 +51,11 @@ all parties in the network: - Network map - Organizational identities - Nodes - - See [Identities](../../reference/identities.html) in the reference section for more information + - See [Identities](../../reference/identities.md) in the reference section for more information - Datatype definitions - - See [Datatype](../../reference/types/datatype.html) in the reference section for more information + - See [Datatype](../../reference/types/datatype.md) in the reference section for more information - Namespaces - - See [Namespaces](../../reference/namespaces.html) for more information + - See [Namespaces](../../reference/namespaces.md) for more information These definitions rely on the same assurances provided by blockchain backed broadcast that FireFly applications do. diff --git a/docs/overview/multiparty/data_exchange.md b/doc-site/docs/overview/multiparty/data_exchange.md similarity index 95% rename from docs/overview/multiparty/data_exchange.md rename to doc-site/docs/overview/multiparty/data_exchange.md index 5647c7f5e..189dd7da6 100644 --- a/docs/overview/multiparty/data_exchange.md +++ b/doc-site/docs/overview/multiparty/data_exchange.md @@ -1,14 +1,5 @@ --- -layout: i18n_page -title: pages.private_data_exchange -parent: pages.multiparty_features -grand_parent: pages.understanding_firefly -nav_order: 2 ---- - -# Private data exchange -{: .no_toc } - +title: Private data exchange --- ## Introduction diff --git a/docs/overview/multiparty/deterministic.md b/doc-site/docs/overview/multiparty/deterministic.md similarity index 94% rename from docs/overview/multiparty/deterministic.md rename to doc-site/docs/overview/multiparty/deterministic.md index cbc0c90e0..2b2891023 100644 --- a/docs/overview/multiparty/deterministic.md +++ b/doc-site/docs/overview/multiparty/deterministic.md @@ -1,14 +1,5 @@ --- -layout: i18n_page -title: pages.deterministic -parent: pages.multiparty_features -grand_parent: pages.understanding_firefly -nav_order: 4 ---- - -# Deterministic Compute -{: .no_toc } - +title: Deterministic Compute --- ## Introduction @@ -55,7 +46,7 @@ mature blockchain technology, and all multi-party systems should consider exploi - Gives you an anchor to attach to something in the real world - This is the magic behind non-fungible tokens (NTFs) - The proven technology for this is a shared ledger of its creation, and ownership changes - - Learn more in the [Tokens](../../tutorials/tokens/index.html) section + - Learn more in the [Tokens](../../tutorials/tokens/index.md) section - An agreed sequence of events - The foundation tool that allows the building of higher level constructs (including tokens) - Not previously available when business ecosystems used HTTP/Messaging transports alone @@ -66,7 +57,7 @@ mature blockchain technology, and all multi-party systems should consider exploi - The glue that binds a piece of private data, to a proof that you have a copy of that data - This is the basis of "pinning" data to the blockchain, without sharing its contents - Care needs to be taken to make sure the data is unique enough to make the hash secure - - Learn more in the [Gateway Features](../gateway_features.html#manage-decentralized-data-nfts-etc) section + - Learn more in the [Gateway Features](../gateway_features.md#manage-decentralized-data-nfts-etc) section ## Advanced Cryptography and Privacy Preserving Trusted Compute @@ -117,4 +108,3 @@ business relationships, by being able to agree the order and sequence of a set o tools to digitize processes that previously took physical documents flying round the world, into near-immediate digital agreement where the arbitration of a dispute can be resolved at a tiny fraction of what would have been possible without a shared and immutable audit trail of who said what when. - diff --git a/docs/overview/multiparty_features.md b/doc-site/docs/overview/multiparty/index.md similarity index 92% rename from docs/overview/multiparty_features.md rename to doc-site/docs/overview/multiparty/index.md index baaaabcf8..4ac6d267e 100644 --- a/docs/overview/multiparty_features.md +++ b/doc-site/docs/overview/multiparty/index.md @@ -1,24 +1,9 @@ --- -layout: i18n_page -title: pages.multiparty_features -parent: pages.understanding_firefly -nav_order: 5 -has_children: true +title: Multiparty Features --- # Enterprise multi-party systems -{: .no_toc } - -## Table of contents - -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- - ## Introduction Multiparty mode has all the features in Gateway mode with the added benefit of multi-party process flows. @@ -31,7 +16,7 @@ By combining these technologies with existing best practice technologies for data security in regulated industries, multi-party systems allow businesses to collaborate in ways previously impossible. -![Multiparty Mode](../images/multiparty_mode.png "Multiparty Mode") +![Multiparty Mode](../../images/multiparty_mode.png "Multiparty Mode") Through agreement on a common source of truth, such as the completion of a step in a business process to proceed, or the existence and ownership of a unique asset, businesses diff --git a/docs/overview/multiparty/multiparty_flow.md b/doc-site/docs/overview/multiparty/multiparty_flow.md similarity index 97% rename from docs/overview/multiparty/multiparty_flow.md rename to doc-site/docs/overview/multiparty/multiparty_flow.md index 94fa6da35..f2fa60483 100644 --- a/docs/overview/multiparty/multiparty_flow.md +++ b/doc-site/docs/overview/multiparty/multiparty_flow.md @@ -1,14 +1,5 @@ --- -layout: i18n_page -title: pages.multiparty_flow -parent: pages.multiparty_features -grand_parent: pages.understanding_firefly -nav_order: 1 ---- - -# Multiparty Process Flows -{: .no_toc } - +title: Multiparty Process Flows --- ## Flow features @@ -136,7 +127,7 @@ of value the blockchain can provide to differentiate your solution from a centra The power provided by deterministic sequencing of events, attested by signatures, and pinned to private data might be sufficient for some cases. In others the token constructs are the key value that differentiates the decentralized ecosystem. Whatever it is, it's important it is identified and -crafted carefully. +crafted carefully. > Note that advanced privacy preserving techniques such as zero-knowledge proofs (ZKP) are gaining traction > and hardening in their production readiness and efficiency. Expect these to play an increasing diff --git a/docs/overview/public_vs_permissioned.md b/doc-site/docs/overview/public_vs_permissioned.md similarity index 97% rename from docs/overview/public_vs_permissioned.md rename to doc-site/docs/overview/public_vs_permissioned.md index 41a9ed403..6a3182f3f 100644 --- a/docs/overview/public_vs_permissioned.md +++ b/doc-site/docs/overview/public_vs_permissioned.md @@ -1,20 +1,8 @@ --- -layout: default title: Public and Permissioned -parent: pages.understanding_firefly -nav_order: 6 --- # Public and Permissioned Blockchain -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- ## Public and Permissioned Blockchains diff --git a/docs/overview/supernode_concept.md b/doc-site/docs/overview/supernode_concept.md similarity index 92% rename from docs/overview/supernode_concept.md rename to doc-site/docs/overview/supernode_concept.md index 49fc3f7f1..8450d4431 100644 --- a/docs/overview/supernode_concept.md +++ b/doc-site/docs/overview/supernode_concept.md @@ -1,20 +1,8 @@ --- -layout: i18n_page -title: pages.introduction -parent: pages.understanding_firefly -nav_order: 1 +title: Introduction --- # Introduction to Hyperledger FireFly -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- ## Your Gateway to Web3 Technologies @@ -56,4 +44,3 @@ Without a technology like Hyperledger FireFly, the application layer becomes ext Tens of thousands of lines of complex low-level "plumbing" / "middleware" code is required to integrate the web3 infrastructure into the application. This code provides zero unique business value to the solution, but can consume a huge proportion of the engineering budget and maintenance cost if built bespoke within a solution. - diff --git a/docs/overview/usage_patterns.md b/doc-site/docs/overview/usage_patterns.md similarity index 83% rename from docs/overview/usage_patterns.md rename to doc-site/docs/overview/usage_patterns.md index 19ea49699..07ac9ded0 100644 --- a/docs/overview/usage_patterns.md +++ b/doc-site/docs/overview/usage_patterns.md @@ -1,19 +1,5 @@ --- -layout: i18n_page -title: pages.usage_patterns -parent: pages.understanding_firefly -nav_order: 2 ---- - -# Usage Patterns -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - +title: Usage Patterns --- There are two modes of usage for Hyperledger Firefly: **Web3 Gateway** and **Multiparty** @@ -28,6 +14,7 @@ Web3 Gateway mode lets you interact with any Web3 application, regardless of whe is being used by other members of your business network. In this mode you can: + - Transfer tokenized value - Invoke any other type of smart contract - Index data from the blockchain @@ -36,7 +23,7 @@ In this mode you can: - Use a _private_ address book to manage signing identities and relationships - ... and much more -Learn more about [Web3 Gateway Mode](./gateway_features.html). +Learn more about [Web3 Gateway Mode](./gateway_features.md). ## Multiparty Mode @@ -48,6 +35,7 @@ This allows sophisticated applications to be built, that all use the pluggable A end-to-end business value in an enterprise context. In this mode you can do everything you could do in Web3 Gateway mode, plus: + - Share and enforce common data formats - Exchange data privately, via an encrypted data bus - Structured JSON data payloads @@ -59,4 +47,4 @@ In this mode you can do everything you could do in Web3 Gateway mode, plus: - Use a _shared_ address book to manage signing identities and relationships - ... and much more -Learn more about [Multiparty Mode](./multiparty_features.html). +Learn more about [Multiparty Mode](./multiparty/index.md). diff --git a/docs/reference/api_post_syntax.md b/doc-site/docs/reference/api_post_syntax.md similarity index 79% rename from docs/reference/api_post_syntax.md rename to doc-site/docs/reference/api_post_syntax.md index eb8080b42..e53de9eb3 100644 --- a/docs/reference/api_post_syntax.md +++ b/doc-site/docs/reference/api_post_syntax.md @@ -1,19 +1,5 @@ --- -layout: i18n_page -title: pages.api_post_syntax -parent: pages.reference -nav_order: 4 ---- - -# API POST Syntax -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - +title: API POST Syntax --- ## Syntax Overview @@ -22,10 +8,10 @@ Endpoints that allow submitting a transaction allow an optional query parameter This is useful for endpoints such as registration, where the client app cannot proceed until the transaction is complete and the member/node is registered. Rather than making a request to register a member/node and then repeatedly polling the API to check to see if it succeeded, an HTTP client can use this query parameter and block until registration is complete. -> **NOTE**: This does *not* mean that any other member of the network has received, processed, or responded to the message. It just means that the transaction is complete from the perspective of the FireFly node to which the transaction was submitted. +> **NOTE**: This does _not_ mean that any other member of the network has received, processed, or responded to the message. It just means that the transaction is complete from the perspective of the FireFly node to which the transaction was submitted. ## Example API Call `POST` `/api/v1/messages/broadcast?confirm=true` -This will broadcast a message and wait for the message to be confirmed before returning. \ No newline at end of file +This will broadcast a message and wait for the message to be confirmed before returning. diff --git a/docs/reference/api_query_syntax.md b/doc-site/docs/reference/api_query_syntax.md similarity index 52% rename from docs/reference/api_query_syntax.md rename to doc-site/docs/reference/api_query_syntax.md index d74b2515e..a3796b3ee 100644 --- a/docs/reference/api_query_syntax.md +++ b/doc-site/docs/reference/api_query_syntax.md @@ -1,24 +1,11 @@ --- -layout: i18n_page -title: pages.api_query_syntax -parent: pages.reference -nav_order: 3 ---- - -# API Query Syntax -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - +title: API Query Syntax --- ## Syntax Overview REST collections provide filter, `skip`, `limit` and `sort` support. + - The field in the message is used as the query parameter - Syntax: `field=[modifiers][operator]match-string` - When multiple query parameters are supplied these are combined with AND @@ -44,19 +31,19 @@ Table of filter operations, which must be the first character of the query strin Operators are a type of comparison operation to perform against the match string. -| Operator | Description | -|----------|------------------------------------| -| `=` | Equal | -| (none) | Equal (shortcut) | -| `@` | Containing | -| `^` | Starts with | -| `$` | Ends with | -| `<<` | Less than | -| `<` | Less than (shortcut) | -| `<=` | Less than or equal | -| `>>` | Greater than | -| `>` | Greater than (shortcut) | -| `>=` | Greater than or equal | +| Operator | Description | +| -------- | ----------------------- | +| `=` | Equal | +| (none) | Equal (shortcut) | +| `@` | Containing | +| `^` | Starts with | +| `$` | Ends with | +| `<<` | Less than | +| `<` | Less than (shortcut) | +| `<=` | Less than or equal | +| `>>` | Greater than | +| `>` | Greater than (shortcut) | +| `>=` | Greater than or equal | > Shortcuts are only safe to use when your match > string starts with `a-z`, `A-Z`, `0-9`, `-` or `_`. @@ -67,7 +54,7 @@ Modifiers can appear before the operator, to change its behavior. | Modifier | Description | -|----------|------------------------------------------------| +| -------- | ---------------------------------------------- | | `!` | Not - negates the match | | `:` | Case insensitive | | `?` | Treat empty match string as null | @@ -76,20 +63,20 @@ behavior. ## Detailed examples -| Example | Description | -|--------------|--------------------------------------------| -| `cat` | Equals "cat" | -| `=cat` | Equals "cat" (same) | -| `!=cat` | Not equal to "cat" | -| `:=cat` | Equal to "CAT", "cat", "CaT etc. | -| `!:cat` | Not equal to "CAT", "cat", "CaT etc. | -| `=!cat` | Equal to "!cat" (! is after operator) | -| `^cats/` | Starts with "cats/" | -| `$_cat` | Ends with with "_cat" | -| `!:^cats/` | Does not start with "cats/", "CATs/" etc. | -| `!$-cat` | Does not end with "-cat" | -| `?=` | Is null | -| `!?=` | Is not null | +| Example | Description | +| ---------- | ----------------------------------------- | +| `cat` | Equals "cat" | +| `=cat` | Equals "cat" (same) | +| `!=cat` | Not equal to "cat" | +| `:=cat` | Equal to "CAT", "cat", "CaT etc. | +| `!:cat` | Not equal to "CAT", "cat", "CaT etc. | +| `=!cat` | Equal to "!cat" (! is after operator) | +| `^cats/` | Starts with "cats/" | +| `$_cat` | Ends with with "\_cat" | +| `!:^cats/` | Does not start with "cats/", "CATs/" etc. | +| `!$-cat` | Does not end with "-cat" | +| `?=` | Is null | +| `!?=` | Is not null | ## Time range example @@ -101,6 +88,7 @@ field using AND semantics (with the `[`) modifier: ``` So this means: + - `created` greater than `2021-01-01T00:00:00Z` - `AND` -- `created` less than or equal to `2021-01-02T00:00:00Z` \ No newline at end of file +- `created` less than or equal to `2021-01-02T00:00:00Z` diff --git a/docs/reference/blockchain_operation_status.md b/doc-site/docs/reference/blockchain_operation_status.md similarity index 91% rename from docs/reference/blockchain_operation_status.md rename to doc-site/docs/reference/blockchain_operation_status.md index 28d7a059e..991f26ee2 100644 --- a/docs/reference/blockchain_operation_status.md +++ b/doc-site/docs/reference/blockchain_operation_status.md @@ -1,25 +1,12 @@ --- -layout: default title: Blockchain Operation Status -parent: pages.reference -nav_order: 5 --- # Blockchain Operation Status -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- - ## Blockchain Operations -Every FireFly [Transaction](./types/transaction.html) can involve zero or more [Operations](./types/operation.html). Blockchain operations are handled by the blockchain connector configured for the namespace and represent a blockchain transaction being handled by that connector. +Every FireFly [Transaction](./types/transaction.md) can involve zero or more [Operations](./types/operation.md). Blockchain operations are handled by the blockchain connector configured for the namespace and represent a blockchain transaction being handled by that connector. ## Blockchain Operation Status @@ -35,30 +22,30 @@ To access detailed information about a blockchain operation FireFly 1.2 introduc ```json { - "id": "04a8b0c4-03c2-4935-85a1-87d17cddc20a", - "created": "2022-05-16T01:23:15Z", - "namespace": "ns1", - "tx": "99543134-769b-42a8-8be4-a5f8873f969d", - "type": "blockchain_invoke", - "status": "Succeeded", - "plugin": "ethereum", - "input": { - // Input used to initiate the blockchain operation - }, - "output": { - // Minimal blockchain operation data necessary - // to resolve the FF transaction - }, - "detail": { - // Full blockchain operation information, including sub-status - // transitions that took place for the operation to succeed. - } + "id": "04a8b0c4-03c2-4935-85a1-87d17cddc20a", + "created": "2022-05-16T01:23:15Z", + "namespace": "ns1", + "tx": "99543134-769b-42a8-8be4-a5f8873f969d", + "type": "blockchain_invoke", + "status": "Succeeded", + "plugin": "ethereum", + "input": { + // Input used to initiate the blockchain operation + }, + "output": { + // Minimal blockchain operation data necessary + // to resolve the FF transaction + }, + "detail": { + // Full blockchain operation information, including sub-status + // transitions that took place for the operation to succeed. + } } ``` ## Detail Status Structure -The structure of a blockchain operation follows the structure described in [Operations](./types/operation.html). In FireFly 1.2, 2 new attributes were added to that structure to allow more detailed status information to be recorded: +The structure of a blockchain operation follows the structure described in [Operations](./types/operation.md). In FireFly 1.2, 2 new attributes were added to that structure to allow more detailed status information to be recorded: - **history** an ordered list of status changes that have taken place during processing of the transaction - **historySummary** an un-ordered list any sub-status type that the blockchain connector uses, and any action type that the blockchain connector carries out as part of processing the transaction. @@ -331,4 +318,4 @@ Below is an example of the `history` for a public blockchain operation. ] ... } -``` \ No newline at end of file +``` diff --git a/docs/reference/config.md b/doc-site/docs/reference/config.md similarity index 99% rename from docs/reference/config.md rename to doc-site/docs/reference/config.md index da6f7387a..72353252d 100644 --- a/docs/reference/config.md +++ b/doc-site/docs/reference/config.md @@ -1,19 +1,5 @@ --- -layout: default title: Configuration Reference -parent: pages.reference -nav_order: 2 ---- - -# Configuration Reference -{: .no_toc } - - - --- diff --git a/docs/reference/events.md b/doc-site/docs/reference/events.md similarity index 95% rename from docs/reference/events.md rename to doc-site/docs/reference/events.md index bbd8087d9..faf51cc39 100644 --- a/docs/reference/events.md +++ b/doc-site/docs/reference/events.md @@ -1,20 +1,8 @@ --- -layout: default title: Event Bus -parent: pages.reference -nav_order: 6 --- # Event Bus -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- [![FireFly Event Bus](../images/firefly_event_bus.jpg)](../images/firefly_event_bus.jpg) @@ -164,7 +152,7 @@ immutable and can never be deleted. > Using Hyperledger Fabric channels for example. -On top of either type of ledger, FireFly provides a private [Group](./types/group) +On top of either type of ledger, FireFly provides a private [Group](./types/group.md) construct to facilitate secure off-chain data exchanges, and to efficiently pin these communications to the blockchain in batches. @@ -183,7 +171,7 @@ information. The categories of event your application can receive are as follows: -> See the [Core Resources/Event](./types/event) page for a full list of event types, +> See the [Core Resources/Event](./types/event.md) page for a full list of event types, > and more details on the data you can expect for each type. ### Blockchain events @@ -192,7 +180,7 @@ FireFly allows your application to subscribe to any event from a blockchain smart contract. In order for applications connected to the FireFly API to receive blockchain events -from a smart contracts, a [ContractListener](./types/contractlistener) fist must be created to instruct +from a smart contracts, a [ContractListener](./types/contractlistener.md) fist must be created to instruct FireFly to listen to those events from the blockchain (via the blockchain plugin). Once you have configured the blockchain event listener, every event detected @@ -227,9 +215,9 @@ token implementations - NFTs and fungible tokens alike: - Approve FireFly processes, indexes and stores the events associated with these actions, -for any [Token Pool](./types/tokenpool) that has been configured on the FireFly node. +for any [Token Pool](./types/tokenpool.md) that has been configured on the FireFly node. -See [Token Transfer](./types/tokentransfer) and [Token Approval](./types/tokenapproval) +See [Token Transfer](./types/tokentransfer.md) and [Token Approval](./types/tokenapproval.md) for more information on the individual operations. The token connector is responsible for mapping from the raw Blockchain Events, to the @@ -266,12 +254,13 @@ attachments) are available+verified in your local FireFly node, _and_ all previo messages on the same `topic` have been processed successfully by your application. Your application just needs to: + 1. Choose a suitable `topic` for your messages that determines the ordered stream it is part of. Such as a business transaction identifier. 2. Make sure the application does not acknowledge a message, until it has finished processing it. -> See [Message](./types/message) for more information +> See [Message](./types/message.md) for more information ## Transaction submission events @@ -280,4 +269,4 @@ These events are emitted each time a new transaction is initiated via the Firefl These events are only emitted on the local FireFly node that initiates an activity. For more information about FireFly Transactions, and how they relate to blockchain -transactions, see [Transaction](./types/transaction). +transactions, see [Transaction](./types/transaction.md). diff --git a/docs/reference/firefly_interface_format.md b/doc-site/docs/reference/firefly_interface_format.md similarity index 62% rename from docs/reference/firefly_interface_format.md rename to doc-site/docs/reference/firefly_interface_format.md index 64b6064c9..e9d123856 100644 --- a/docs/reference/firefly_interface_format.md +++ b/doc-site/docs/reference/firefly_interface_format.md @@ -1,37 +1,25 @@ --- -layout: default title: FireFly Interface Format -parent: pages.reference -nav_order: 8 --- # FireFly Interface Format -{: .no_toc } FireFly defines a common, blockchain agnostic way to describe smart contracts. This is referred to as a **Contract Interface**, and it is written in the FireFly Interface (FFI) format. It is a simple JSON document that has a name, a namespace, a version, a list of methods, and a list of events. -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- - ## Overview There are four required fields when broadcasting a contract interface in FireFly: a `name`, a `version`, a list of `methods`, and a list of `events`. A `namespace` field will also be filled in automatically based on the URL path parameter. Here is an example of the structure of the required fields: ```json { - "name": "example", - "version": "v1.0.0", - "methods": [], - "events": [] + "name": "example", + "version": "v1.0.0", + "methods": [], + "events": [] } ``` -> **NOTE**: Contract interfaces are scoped to a namespace. Within a namespace each contract interface must have a unique name and version combination. The same name and version combination can exist in *different* namespaces simultaneously. +> **NOTE**: Contract interfaces are scoped to a namespace. Within a namespace each contract interface must have a unique name and version combination. The same name and version combination can exist in _different_ namespaces simultaneously. ## Method @@ -39,11 +27,11 @@ Let's look at a what goes inside the `methods` array now. It is also a JSON obje ```json { - "name": "add", - "description": "Add two numbers together", - "params": [], - "returns": [], - "details": {} + "name": "add", + "description": "Add two numbers together", + "params": [], + "returns": [], + "details": {} } ``` @@ -53,10 +41,10 @@ What goes into the `events` array is very similar. It is also a JSON object that ```json { - "name": "added", - "description": "An event that occurs when numbers have been added", - "params": [], - "details": {} + "name": "added", + "description": "An event that occurs when numbers have been added", + "params": [], + "details": {} } ``` @@ -66,11 +54,11 @@ Both `methods`, and `events` have lists of `params` or `returns`, and the type o ```json { - "name": "x", - "schema": { - "type": "integer", - "details": {} - } + "name": "x", + "schema": { + "type": "integer", + "details": {} + } } ``` @@ -82,11 +70,11 @@ The `schema` field accepts [JSON Schema (version 2020-12)](https://json-schema.o - A `type` field is always mandatory - The list of valid types is: - - `boolean` - - `integer` - - `string` - - `object` - - `array` + - `boolean` + - `integer` + - `string` + - `object` + - `array` - Blockchain plugins can add their own specific requirements to this list of validation rules > **NOTE**: Floats or decimals are not currently accepted because certain underlying blockchains (e.g. Ethereum) only allow integers @@ -96,15 +84,15 @@ The type field here is the JSON input type when making a request to FireFly to i ### Schema details -The details field is quite important in some cases. Because the `details` field is passed to the blockchain plugin, it is used to encapsulate blockchain specific type information about a particular field. Additionally, because each blockchain plugin can add rules to the list of schema requirements above, a blockchain plugin can enforce that certain fields are always present within the `details` field. +The details field is quite important in some cases. Because the `details` field is passed to the blockchain plugin, it is used to encapsulate blockchain specific type information about a particular field. Additionally, because each blockchain plugin can add rules to the list of schema requirements above, a blockchain plugin can enforce that certain fields are always present within the `details` field. For example, the Ethereum plugin always needs to know what Solidity type the field is. It also defines several optional fields. A full Ethereum details field may look like: ```json { - "type": "uint256", - "internalType": "uint256", - "indexed": false + "type": "uint256", + "internalType": "uint256", + "indexed": false } ``` @@ -120,81 +108,81 @@ Putting it all together, here is a full example of the FireFly Interface format ```json { - "namespace": "default", - "name": "SimpleStorage", - "description": "A simple smart contract that stores and retrieves an integer on-chain", - "version": "v1.0.0", - "methods": [ + "namespace": "default", + "name": "SimpleStorage", + "description": "A simple smart contract that stores and retrieves an integer on-chain", + "version": "v1.0.0", + "methods": [ + { + "name": "get", + "description": "Retrieve the value of the stored integer", + "params": [], + "returns": [ { - "name": "get", - "description": "Retrieve the value of the stored integer", - "params": [], - "returns": [ - { - "name": "output", - "schema": { - "type": "integer", - "details": { - "type": "uint256", - "internalType": "uint256" - } - } - } - ], + "name": "output", + "schema": { + "type": "integer", "details": { - "stateMutability": "viewable" + "type": "uint256", + "internalType": "uint256" } - }, + } + } + ], + "details": { + "stateMutability": "viewable" + } + }, + { + "name": "set", + "description": "Set the stored value on-chain", + "params": [ { - "name": "set", - "description": "Set the stored value on-chain", - "params": [ - { - "name": "newValue", - "schema": { - "type": "integer", - "details": { - "type": "uint256", - "internalType": "uint256" - } - } - } - ], - "returns": [], + "name": "newValue", + "schema": { + "type": "integer", "details": { - "stateMutability": "payable" + "type": "uint256", + "internalType": "uint256" } + } } - ], - "events": [ + ], + "returns": [], + "details": { + "stateMutability": "payable" + } + } + ], + "events": [ + { + "name": "Changed", + "description": "An event that is fired when the stored integer value changes", + "params": [ + { + "name": "from", + "schema": { + "type": "string", + "details": { + "type": "address", + "internalType": "address", + "indexed": true + } + } + }, { - "name": "Changed", - "description": "An event that is fired when the stored integer value changes", - "params": [ - { - "name": "from", - "schema": { - "type": "string", - "details": { - "type": "address", - "internalType": "address", - "indexed": true - } - } - }, - { - "name": "value", - "schema": { - "type": "integer", - "details": { - "type": "uint256", - "internalType": "uint256" - } - } - } - ], - "details": {} + "name": "value", + "schema": { + "type": "integer", + "details": { + "type": "uint256", + "internalType": "uint256" + } + } } - ] + ], + "details": {} + } + ] } -``` \ No newline at end of file +``` diff --git a/docs/reference/idempotency.md b/doc-site/docs/reference/idempotency.md similarity index 78% rename from docs/reference/idempotency.md rename to doc-site/docs/reference/idempotency.md index b8470e507..fa99500d7 100644 --- a/docs/reference/idempotency.md +++ b/doc-site/docs/reference/idempotency.md @@ -1,20 +1,8 @@ --- -layout: default title: Idempotency Keys -parent: pages.reference -nav_order: 10 --- # Idempotency Keys -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- ## Idempotency @@ -27,9 +15,9 @@ This is the well accepted approach for REST APIs over HTTP/HTTPS to achieve resi can fail in indeterminate ways. For example in a request or gateway timeout situation, the requester is unable to know whether the request will or will not eventually be processed. -There are various types of FireFly [transaction](../reference/types/transaction.html) that can be submitted. +There are various types of FireFly [transaction](../reference/types/transaction.md) that can be submitted. These include direct submission of blockchain transactions to a smart contract, as well as more complex -transactions including coordination of multiple [operations](../reference/types/operation.html) +transactions including coordination of multiple [operations](../reference/types/operation.md) across on-chain and off-chain connectors. In order for Hyperledger FireFly to deduplicate transactions, and make them idempotent, the application @@ -46,29 +34,30 @@ So if there is a network connectivity failure, or an abrupt termination of eithe can safely attempt to resubmit the REST API call and be returned a `409 Conflict` HTTP code. Examples of how an app might construct such an idempotencyKey include: + - Unique business identifiers from the request that comes into its API up-stream - passing idempotency along the chain - A hash of the business unique data that relates to the request - maybe all the input data of a blockchain transaction for example, if that payload is guaranteed to be unique. - > Be careful of cases where the business data might _not_ be unique - like a transfer of 10 coins from A to B. - > - > Such a transfer could happen multiple times, and each would be a separate business transaction. - > - > Where as transfer with invoice number `abcd1234` of 10 coins from A to B would be assured to be unique. + > Be careful of cases where the business data might _not_ be unique - like a transfer of 10 coins from A to B. + > + > Such a transfer could happen multiple times, and each would be a separate business transaction. + > + > Where as transfer with invoice number `abcd1234` of 10 coins from A to B would be assured to be unique. - A unique identifier of a business transaction generated within the application and stored in its database before submission - > This moves the challenge up one layer into your application. How does that unique ID get generated? Is that - > itself idempotent? + > This moves the challenge up one layer into your application. How does that unique ID get generated? Is that + > itself idempotent? ## Operation Idempotency FireFly provides an idempotent interface downstream to connectors. -Each [operation](../reference/types/operation.html) within a FireFly [transaction](../reference/types/transaction.html) +Each [operation](../reference/types/operation.md) within a FireFly [transaction](../reference/types/transaction.md) receives a unique ID within the overall transaction that is used as an idempotency key when invoking that connector. Well formed connectors honor this idempotency key internally, ensuring that the end-to-end transaction submission is idempotent. Key examples of such connectors are EVMConnect and others built on the -[Blockchain Connector Toolkit](../architecture/blockchain_connector_framework.html). +[Blockchain Connector Toolkit](../architecture/blockchain_connector_framework.md). When an operation is retried automatically, the same idempotency key is re-used to avoid resubmission. @@ -80,7 +69,7 @@ This code include exponential backoff retry, that can be enabled with a simple b of FireFly core. The minimum retry, maximum retry, and backoff factor can be tuned individually as well on each connector. -See [Configuration Reference](../reference/config.html) for more information. +See [Configuration Reference](../reference/config.md) for more information. ## Administrative operation retry @@ -88,6 +77,5 @@ The `operations/{operationId}/retry` API can be called administratively to resub transaction that has reached `Failed` status, or otherwise been determined by an operator/monitor to be unrecoverable within the connector. -In this case, the previous operation is marked `Retried`, a new operation ID is allocated, and +In this case, the previous operation is marked `Retried`, a new operation ID is allocated, and the operation is re-submitted to the connector with this new ID. - diff --git a/docs/reference/identities.md b/doc-site/docs/reference/identities.md similarity index 87% rename from docs/reference/identities.md rename to doc-site/docs/reference/identities.md index 03ba4e058..7a2b51bcc 100644 --- a/docs/reference/identities.md +++ b/doc-site/docs/reference/identities.md @@ -1,20 +1,8 @@ --- -layout: default title: Identities -parent: pages.reference -nav_order: 7 --- # Identities -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- ## Overview @@ -33,7 +21,7 @@ Organizations are the primary identity type in FireFly. They represent a logical attached verifier is therefore a blockchain key (with the exact format depending on the blockchain being used). Every party in a multi-party system must claim a _root organization_ identity as the first step to joining the network. -The root organization `name` and `key` must be defined in the [FireFly config](config.html) (once for every multi-party system). +The root organization `name` and `key` must be defined in the [FireFly config](config.md) (once for every multi-party system). It can be claimed with a POST to `/network/organizations/self`. Organizations may have child identities of any type. @@ -46,7 +34,7 @@ validation provided by that plugin (ie the name of an X.509 certificate or simil claim a node identity when joining the network, which must be a child of one of its organization identities (but it is possible for many nodes to share a parent organization). -The node `name` must be defined in the [FireFly config](config.html) (once for every multi-party system). It can be +The node `name` must be defined in the [FireFly config](config.md) (once for every multi-party system). It can be claimed with a POST to `/network/nodes/self`. Nodes must be a child of an organization, and cannot have any child identities of their own. @@ -86,12 +74,13 @@ every recipient must also have an on-chain and off-chain identity. ### Sender When sending a message, the on-chain identity of the sender is controlled by the `author` and `key` fields. -* If both are blank, the root organization is assumed. -* If `author` alone is specified, it should be the DID of an org or custom identity. The associated + +- If both are blank, the root organization is assumed. +- If `author` alone is specified, it should be the DID of an org or custom identity. The associated verifier will be looked up to use as the `key`. -* If `key` alone is specified, it must match the registered blockchain verifier for an org or custom identity that was previously claimed. +- If `key` alone is specified, it must match the registered blockchain verifier for an org or custom identity that was previously claimed. A reverse lookup will be used to populate the DID for the `author`. -* If `author` and `key` are both specified, they will be used as-is (can be used to send private messages with an unregistered blockchain key). +- If `author` and `key` are both specified, they will be used as-is (can be used to send private messages with an unregistered blockchain key). The resolved `key` will be used to sign the blockchain transaction, which establishes the sender's on-chain identity. @@ -100,9 +89,10 @@ The sender's off-chain identity is always controlled by the `node.name` from the ### Recipients When specifying private message recipients, each one has an `identity` and a `node`. -* If `identity` alone is specified, it should be the DID of an org or custom identity. The first `node` owned by that identity or one of its + +- If `identity` alone is specified, it should be the DID of an org or custom identity. The first `node` owned by that identity or one of its ancestors will be automatically selected. -* If both `identity` and `node` are specified, they will be used as-is. The `node` should be a child of the given `identity` or one of its +- If both `identity` and `node` are specified, they will be used as-is. The `node` should be a child of the given `identity` or one of its ancestors. The `node` in this case will control how the off-chain portion of the message is routed via data exchange. @@ -110,10 +100,11 @@ The `node` in this case will control how the off-chain portion of the message is ### Verification When a message is received, FireFly verifies the following: -* The sender's `author` and `key` are specified in the message. The `author` must be a known org or custom identity. The `key` must match the + +- The sender's `author` and `key` are specified in the message. The `author` must be a known org or custom identity. The `key` must match the blockchain key that was used to sign the on-chain portion of the message. For broadcast messages, the `key` must match the registered verifier for the `author`. -* For private messages, the sending `node` (as reported by data exchange) must be a known node identity which is a child of the message's +- For private messages, the sending `node` (as reported by data exchange) must be a known node identity which is a child of the message's `author` identity or one of its ancestors. The combination of the `author` identity and the `node` must also be found in the message `group`. In addition, the data exchange plugin is responsible for verifying the sending and receiving identities for the off-chain diff --git a/docs/reference/microservices/fftokens.md b/doc-site/docs/reference/microservices/fftokens.md similarity index 91% rename from docs/reference/microservices/fftokens.md rename to doc-site/docs/reference/microservices/fftokens.md index ca3ad3b8a..fce23e9cc 100644 --- a/docs/reference/microservices/fftokens.md +++ b/doc-site/docs/reference/microservices/fftokens.md @@ -1,24 +1,9 @@ --- -layout: default title: fftokens -parent: Microservices -grand_parent: pages.reference -nav_order: 1 --- # fftokens -{: .no_toc } - -## Table of contents - -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- - ## Overview fftokens is a protocol that can be implemented by token connector runtimes in order to be usable by the [fftokens](https://github.com/hyperledger/firefly/blob/main/internal/tokens/fftokens/fftokens.go) plugin in FireFly. @@ -49,6 +34,7 @@ FireFly will store a "pending" token pool after a successful creation, but will { "type": "fungible", "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A", + "namespace": "default", "name": "FFCoin", "symbol": "FFC", "data": "pool-metadata", @@ -61,6 +47,7 @@ FireFly will store a "pending" token pool after a successful creation, but will | --------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | type | string enum | The type of pool to create. Currently supported types are "fungible" and "nonfungible". It is recommended (but not required) that token connectors support both. Unrecognized/unsupported types should be rejected with HTTP 400. | | signer | string | The signing identity to be used for the blockchain transaction, in a format understood by this connector. | +| namespace | string | The namespace of the token pool | | name | string | (OPTIONAL) If supported by this token contract, this is a requested name for the token pool. May be ignored at the connector's discretion. | | symbol | string | (OPTIONAL) If supported by this token contract, this is a requested symbol for the token pool. May be ignored at the connector's discretion. | | requestId | string | (OPTIONAL) A unique identifier for this request. Will be included in the "receipt" websocket event to match receipts to requests. | @@ -71,7 +58,7 @@ FireFly will store a "pending" token pool after a successful creation, but will HTTP 200: pool creation was successful, and the pool details are returned in the response. -_See [Response Types: Token Pool](#token-pool-1)_ +_See [Response Types: Token Pool](#token-pool_1)_ HTTP 202: request was accepted, but pool will be created asynchronously, with "receipt" and "token-pool" events sent later on the websocket. @@ -87,6 +74,7 @@ In a multiparty network, this step will be performed by every member after a suc ``` { + "namespace": "default", "poolLocator": "id=F1", "poolData": "extra-pool-info", "config": {} @@ -95,6 +83,7 @@ In a multiparty network, this step will be performed by every member after a suc | Parameter | Type | Description | | ----------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| namespace | string | The namespace of the token pool | | poolLocator | string | The locator of the pool, as supplied by the output of the pool creation. | | poolData | string | (OPTIONAL) A data string that should be permanently attached to this pool and returned in all events. | | config | object | (OPTIONAL) An arbitrary JSON object where the connector may accept additional parameters if desired. This should be the same `config` object that was passed when the pool was created. | @@ -103,7 +92,7 @@ In a multiparty network, this step will be performed by every member after a suc HTTP 200: pool activation was successful, and the pool details are returned in the response. -_See [Response Types: Token Pool](#token-pool-1)_ +_See [Response Types: Token Pool](#token-pool_1)_ HTTP 202: request was accepted, but pool will be activated asynchronously, with "receipt" and "token-pool" events sent later on the websocket. @@ -121,6 +110,7 @@ Deactivate a token pool to stop receiving events and delete all blockchain liste ``` { + "namespace": "default", "poolLocator": "id=F1", "poolData": "extra-pool-info", "config": {} @@ -129,6 +119,7 @@ Deactivate a token pool to stop receiving events and delete all blockchain liste | Parameter | Type | Description | | ----------- | ------ | ---------------------------------------------------------------------------------------------------- | +| namespace | string | The namespace of the token pool | | poolLocator | string | The locator of the pool, as supplied by the output of the pool creation. | | poolData | string | (OPTIONAL) The data string that was attached to this pool at activation. | | config | object | (OPTIONAL) An arbitrary JSON object where the connector may accept additional parameters if desired. | @@ -146,7 +137,7 @@ _No body_ ### `POST /checkinterface` This is an optional (but recommended) API for token connectors. If implemented, support will be indicated by -the presence of the `interfaceFormat` field in all [Token Pool](#token-pool-1) responses. +the presence of the `interfaceFormat` field in all [Token Pool](#token-pool_1) responses. In the case that a connector supports multiple variants of a given token standard (such as many different ways to structure "mint" or "burn" calls on an underlying smart contract), this API allows the connector to be provided with a full @@ -226,6 +217,7 @@ Mint new tokens. ``` { + "namespace": "default", "poolLocator": "id=F1", "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A", "to": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A", @@ -241,6 +233,7 @@ Mint new tokens. | Parameter | Type | Description | | ----------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| namespace | string | The namespace of the token pool | | poolLocator | string | The locator of the pool, as supplied by the output of the pool creation. | | signer | string | The signing identity to be used for the blockchain transaction, in a format understood by this connector. | | to | string | The identity to receive the minted tokens, in a format understood by this connector. | @@ -266,6 +259,7 @@ Burn tokens. ``` { + "namespace": "default", "poolLocator": "id=F1", "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A", "from": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A", @@ -280,6 +274,7 @@ Burn tokens. | Parameter | Type | Description | | ----------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| namespace | string | The namespace of the token pool | | poolLocator | string | The locator of the pool, as supplied by the output of the pool creation. | | signer | string | The signing identity to be used for the blockchain transaction, in a format understood by this connector. | | from | string | The identity that currently owns the tokens to be burned, in a format understood by this connector. | @@ -304,6 +299,7 @@ Transfer tokens from one address to another. ``` { + "namespace": "default", "poolLocator": "id=F1", "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A", "from": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A", @@ -319,6 +315,7 @@ Transfer tokens from one address to another. | Parameter | Type | Description | | ----------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| namespace | string | The namespace of the token pool | | poolLocator | string | The locator of the pool, as supplied by the output of the pool creation. | | signer | string | The signing identity to be used for the blockchain transaction, in a format understood by this connector. | | from | string | The identity to be used for the source of the transfer, in a format understood by this connector. | @@ -344,6 +341,7 @@ Approve another identity to manage tokens. ``` { + "namespace": "default", "poolLocator": "id=F1", "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A", "operator": "0xb107ed9caa1323b7bc36e81995a4658ec2251951", @@ -357,6 +355,7 @@ Approve another identity to manage tokens. | Parameter | Type | Description | | ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| namespace | string | The namespace of the token pool | | poolLocator | string | The locator of the pool, as supplied by the output of the pool creation. | | signer | string | The signing identity to be used for the blockchain transaction, in a format understood by this connector. | | operator | string | The identity to be approved (or unapproved) for managing the signer's tokens. | @@ -372,6 +371,17 @@ HTTP 202: request was accepted, but approval will occur asynchronously, with "re _See [Response Types: Async Request](#async-request)_ +## Websocket Commands + +In order to start listening for events on a certain namespace, the client needs to send the `start` command. Clients should send this command every time they connect, or after an automatic reconnect. + +``` +{ + "type": "start", + "namespace": "default" +} +``` + ## Websocket Events A connector should expose a websocket at `/api/ws`. All emitted websocket events are a JSON string of the form: @@ -421,37 +431,37 @@ Batched messages must be acked all at once using the ID of the batch. An asynchronous operation has completed. -_See [Response Types: Receipt](#receipt-1)_ +_See [Response Types: Receipt](#receipt_1)_ ### `token-pool` A new token pool has been created or activated. -_See [Response Types: Token Pool](#token-pool-1)_ +_See [Response Types: Token Pool](#token-pool_1)_ ### `token-mint` Tokens have been minted. -_See [Response Types: Token Transfer](#token-transfer-1)_ +_See [Response Types: Token Transfer](#token-transfer_1)_ ### `token-burn` Tokens have been burned. -_See [Response Types: Token Transfer](#token-transfer-1)_ +_See [Response Types: Token Transfer](#token-transfer_1)_ ### `token-transfer` Tokens have been transferred. -_See [Response Types: Token Transfer](#token-transfer-1)_ +_See [Response Types: Token Transfer](#token-transfer_1)_ ### `token-approval` Token approvals have changed. -_See [Response Types: Token Approval](#token-approval-1)_ +_See [Response Types: Token Approval](#token-approval_1)_ ## Response Types @@ -488,6 +498,7 @@ Many operations may happen asynchronously in the background, and will return onl ``` { + "namespace": "default", "type": "fungible", "data": "pool-metadata", "poolLocator": "id=F1", @@ -503,6 +514,7 @@ Many operations may happen asynchronously in the background, and will return onl | Parameter | Type | Description | | --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| namespace | string | The namespace of the token pool | | type | string enum | The type of pool that was created. | | data | string | A copy of the data that was passed in on the creation request. | | poolLocator | string | A string to identify this pool, generated by the connector. Must be unique for each pool created by this connector. Will be passed back on all operations within this pool, and may be packed with relevant data about the pool for later usage (such as the address and type of the pool). | @@ -521,6 +533,7 @@ while a burn will omit the "to" field. ``` { + "namespace": "default", "id": "1", "data": "transfer-metadata", "poolLocator": "id=F1", @@ -537,6 +550,7 @@ while a burn will omit the "to" field. | Parameter | Type | Description | | ----------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| namespace | string | The namespace of the token pool | | id | string | An identifier for this transfer. Must be unique for every transfer within this pool. | | data | string | A copy of the data that was passed in on the mint/burn/transfer request. May be omitted if the token contract does not support a method of attaching extra data (will result in reduced ability for FireFly to correlate the inputs and outputs of the transaction). | | poolLocator | string | The locator of the pool, as supplied by the output of the pool creation. | @@ -553,6 +567,7 @@ while a burn will omit the "to" field. ``` { + "namespace": "default", "id": "1", "data": "transfer-metadata", "poolLocator": "id=F1", @@ -568,6 +583,7 @@ while a burn will omit the "to" field. | Parameter | Type | Description | | ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| namespace | string | The namespace of the token pool | | id | string | An identifier for this approval. Must be unique for every approval within this pool. | | data | string | A copy of the data that was passed in on the approval request. May be omitted if the token contract does not support a method of attaching extra data (will result in reduced ability for FireFly to correlate the inputs and outputs of the transaction). | | poolLocator | string | The locator of the pool, as supplied by the output of the pool creation. | diff --git a/docs/reference/namespaces.md b/doc-site/docs/reference/namespaces.md similarity index 79% rename from docs/reference/namespaces.md rename to doc-site/docs/reference/namespaces.md index 02b6db01c..1200ec695 100644 --- a/docs/reference/namespaces.md +++ b/doc-site/docs/reference/namespaces.md @@ -1,20 +1,8 @@ --- -layout: default title: Namespaces -parent: pages.reference -nav_order: 9 --- # Namespaces -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- [![FireFly Namespaces Example](../images/hyperledger-firefly-namespaces-example-with-org.png "FireFly namespaces example")](../images/hyperledger-firefly-namespaces-example-with-org.png) @@ -22,18 +10,19 @@ nav_order: 9 Namespaces are a construct for segregating data and operations within a FireFly supernode. Each namespace is an isolated environment within a FireFly runtime, that allows independent configuration of: - * Plugin and infrastructure components - * API security - * Identity broadcasting - * On-chain data indexing - * How datatypes, locations of on-chain contrats, etc. should be shared +- Plugin and infrastructure components +- API security +- Identity broadcasting +- On-chain data indexing +- How datatypes, locations of on-chain contrats, etc. should be shared They can be thought of in two basic modes: ### Multi-party Namespaces + This namespace is shared with one or more other FireFly nodes. It requires three types of communication plugins - blockchain, data exchange, and shared storage. Organization and node identities must be claimed with an identity broadcast when joining the namespace, which establishes credentials for blockchain and off-chain communication. Shared objects can be defined in the namespace (such as datatypes and token pools), and details of them will be implicitly broadcast to other members. -This type of namespace is used when multiple parties need to share on- and off-chain data and agree upon the ordering and authenticity of that data. For more information, see the [multi-party system](../overview/multiparty_features.md) overview. +This type of namespace is used when multiple parties need to share on- and off-chain data and agree upon the ordering and authenticity of that data. For more information, see the [multi-party system](../overview/multiparty/index.md) overview. ### Gateway Namespaces @@ -120,58 +109,62 @@ namespaces: The `namespaces.predefined` object contains the follow sub-keys: -* `defaultKey` is a blockchain key used to sign transactions when none is specified (in multi-party mode, +- `defaultKey` is a blockchain key used to sign transactions when none is specified (in multi-party mode, defaults to the org key) -* `plugins` is an array of plugin names to be activated for this namespace (defaults to +- `plugins` is an array of plugin names to be activated for this namespace (defaults to all available plugins if omitted) -* `multiparty.networkNamespace` is the namespace name to be sent in plugin calls, if it differs from the +- `multiparty.networkNamespace` is the namespace name to be sent in plugin calls, if it differs from the locally used name (useful for interacting with multiple shared namespaces of the same name - defaults to the value of `name`) -* `multiparty.enabled` controls if multi-party mode is enabled (defaults to true if an org key or +- `multiparty.enabled` controls if multi-party mode is enabled (defaults to true if an org key or org name is defined on this namespace _or_ in the deprecated `org` section at the root) -* `multiparty.org` is the root org identity for this multi-party namespace (containing `name`, +- `multiparty.org` is the root org identity for this multi-party namespace (containing `name`, `description`, and `key`) -* `multiparty.node` is the local node identity for this multi-party namespace (containing `name` and +- `multiparty.node` is the local node identity for this multi-party namespace (containing `name` and `description`) -* `multiparty.contract` is an array of objects describing the location(s) of a FireFly multi-party +- `multiparty.contract` is an array of objects describing the location(s) of a FireFly multi-party smart contract. Its children are blockchain-agnostic `location` and `firstEvent` fields, with formats identical to the same fields on custom contract interfaces and contract listeners. The blockchain plugin will interact with the first contract in the list until instructions are received to terminate it and migrate to the next. ### Config Restrictions -* `name` must be unique on this node -* for historical reasons, "ff_system" is a reserved string and cannot be used as a `name` or `multiparty.networkNamespace` -* a `database` plugin is required for every namespace -* if `multiparty.enabled` is true, plugins _must_ include one each of `blockchain`, `dataexchange`, and + +- `name` must be unique on this node +- for historical reasons, "ff_system" is a reserved string and cannot be used as a `name` or `multiparty.networkNamespace` +- a `database` plugin is required for every namespace +- if `multiparty.enabled` is true, plugins _must_ include one each of `blockchain`, `dataexchange`, and `sharedstorage` -* if `multiparty.enabled` is false, plugins _must not_ include `dataexchange` or `sharedstorage` -* at most one of each type of plugin is allowed per namespace, except for tokens (which +- if `multiparty.enabled` is false, plugins _must not_ include `dataexchange` or `sharedstorage` +- at most one of each type of plugin is allowed per namespace, except for tokens (which may have many per namespace) All namespaces must be called out in the FireFly config file in order to be valid. Namespaces found in the database but _not_ represented in the config file will be ignored. ## Definitions -In FireFly, definitions are immutable payloads that are used to define identities, datatypes, smart contract interfaces, token pools, and other constructs. Each type of definition in FireFly has a schema that it must adhere to. Some definitions also have a name and a version which must be unique within a namespace. In a multiparty namespace, definitions are broadcasted to other organizations. + +In FireFly, definitions are immutable payloads that are used to define identities, datatypes, smart contract interfaces, token pools, and other constructs. Each type of definition in FireFly has a schema that it must adhere to. Some definitions also have a name and a version which must be unique within a namespace. In a multiparty namespace, definitions are broadcasted to other organizations. ## Local Definitions The following are all "definition" types in FireFly: -* datatype -* group -* token pool -* contract interface -* contract API -* organization (deprecated) -* node (deprecated) -* identity claim -* identity verification -* identity update + +- datatype +- group +- token pool +- contract interface +- contract API +- organization (deprecated) +- node (deprecated) +- identity claim +- identity verification +- identity update For gateway namespaces, the APIs which create these definitions will become an immediate local database insert, instead of performing a broadcast. Additional caveats: -* identities in this mode will not undergo any claim/verification process, + +- identities in this mode will not undergo any claim/verification process, but will be created and stored locally -* datatypes and groups will not be supported, as they are only useful in the context - of messaging (which is disabled in gateway namespaces) \ No newline at end of file +- datatypes and groups will not be supported, as they are only useful in the context + of messaging (which is disabled in gateway namespaces) diff --git a/docs/reference/tls.md b/doc-site/docs/reference/tls.md similarity index 56% rename from docs/reference/tls.md rename to doc-site/docs/reference/tls.md index b709d429f..d181170aa 100644 --- a/docs/reference/tls.md +++ b/doc-site/docs/reference/tls.md @@ -1,62 +1,45 @@ --- -layout: i18n_page -title: pages.tls -parent: pages.reference -nav_order: 11 ---- - -# TLS -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - +title: TLS --- ## TLS Overview - To enable TLS in Firefly, there is a configuration available to provide certificates and keys. The common configuration is as such: ```yaml tls: - enabled: true/false # Toggle on or off TLS - caFile: - certFile: - keyFile: - clientAuth: true/false # Only applicable to the server side, to toggle on or off client authentication - requiredDNAttributes: A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) + enabled: true/false # Toggle on or off TLS + caFile: + certFile: + keyFile: + clientAuth: true/false # Only applicable to the server side, to toggle on or off client authentication + requiredDNAttributes: A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) ``` -**NOTE** The CAs, certificates and keys have to be in PEM format. +**NOTE** The CAs, certificates and keys have to be in PEM format. ## Configuring TLS for the API server Using the above configuration, we can place it under the `http` config and enable TLS or mTLS for any API call. -[See this config section for details](config.html#httptls) +[See this config section for details](config.md#httptls) ## Configuring TLS for the webhooks Using the above configuration, we can place it under the `events.webhooks` config and enable TLS or mTLS for any webhook call. -[See this config section for details](config.html#eventswebhookstls) - +[See this config section for details](config.md#eventswebhookstls) ## Configuring clients and websockets -Firefly has a set of HTTP clients and websockets that communicate the external endpoints and services that could be secured using TLS. -In order to configure these clients, we can use the same configuration as above in the respective places in the config which relate to those clients. - -For example, if you wish to configure the ethereum blockchain connector with TLS you would look at [this config section](config.html#pluginsblockchainethereumethconnecttls) +Firefly has a set of HTTP clients and websockets that communicate the external endpoints and services that could be secured using TLS. +In order to configure these clients, we can use the same configuration as above in the respective places in the config which relate to those clients. -For more clients, search in the [configuration reference](config.html) for a TLS section. +For example, if you wish to configure the ethereum blockchain connector with TLS you would look at [this config section](config.md#pluginsblockchainethereumethconnecttls) +For more clients, search in the [configuration reference](config.md) for a TLS section. ## Enhancing validation of certificates diff --git a/docs/reference/types/_includes/batch_description.md b/doc-site/docs/reference/types/_includes/batch_description.md similarity index 100% rename from docs/reference/types/_includes/batch_description.md rename to doc-site/docs/reference/types/_includes/batch_description.md diff --git a/docs/reference/types/_includes/blockchainevent_description.md b/doc-site/docs/reference/types/_includes/blockchainevent_description.md similarity index 91% rename from docs/reference/types/_includes/blockchainevent_description.md rename to doc-site/docs/reference/types/_includes/blockchainevent_description.md index 277850b22..67d37f978 100644 --- a/docs/reference/types/_includes/blockchainevent_description.md +++ b/doc-site/docs/reference/types/_includes/blockchainevent_description.md @@ -1,9 +1,9 @@ Blockchain Events are detected by the blockchain plugin: -1. When a [ContractListener](./contractlistener.html) has been +1. When a [ContractListener](./contractlistener.md) has been configured against any custom smart contract through the FireFly API 2. Indirectly via a Token Connector, which understands the correct events - to listen to for a [Token Pool](./tokenpool.html) configured against a + to listen to for a [Token Pool](./tokenpool.md) configured against a standard such as ERC-20/ERC-721/ERC-1155 3. Automatically by FireFly core, for the BatchPin contract that can be used for high throughput batched pinning of off-chain data transfers @@ -28,11 +28,7 @@ An example `protocolId` string is: `000000000041/000020/000003` - `000020` - this is the transaction index within that block - `000003` - this is the event (/log) index within that transaction - The string is alphanumerically sortable as a plain string; > Sufficient zero padding is included at each layer to support future expansion > without creating a string that would no longer sort correctly. - - - diff --git a/docs/reference/types/_includes/contractapi_description.md b/doc-site/docs/reference/types/_includes/contractapi_description.md similarity index 95% rename from docs/reference/types/_includes/contractapi_description.md rename to doc-site/docs/reference/types/_includes/contractapi_description.md index 28cf61665..1a2f920b0 100644 --- a/docs/reference/types/_includes/contractapi_description.md +++ b/doc-site/docs/reference/types/_includes/contractapi_description.md @@ -11,7 +11,7 @@ smart contract. > the FireFly events (of type `blockchain_event_received`) that are emitted > for each detected blockchain event. > -> For more information see the [Events](../events.html) reference section. +> For more information see the [Events](../events.md) reference section. ### URL @@ -28,7 +28,7 @@ For the default namespace, this can be shortened to: Contract APIs are registered against: 1. A FireFly Interface (FFI) definition, which defines in a blockchain agnostic - format the list of functions/events supported by the smart contract. Also + format the list of functions/events supported by the smart contract. Also detailed type information about the inputs/outputs to those functions/events. 2. An optional `location` configured on the Contract API describes where the diff --git a/docs/reference/types/_includes/contractlistener_description.md b/doc-site/docs/reference/types/_includes/contractlistener_description.md similarity index 93% rename from docs/reference/types/_includes/contractlistener_description.md rename to doc-site/docs/reference/types/_includes/contractlistener_description.md index cad02645b..e6c1721b8 100644 --- a/docs/reference/types/_includes/contractlistener_description.md +++ b/doc-site/docs/reference/types/_includes/contractlistener_description.md @@ -2,5 +2,5 @@ A contract listener configures FireFly to stream events from the blockchain, from a specific location on the blockchain, according to a given definition of the interface for that event. -Check out the [Custom Contracts Tutorial](../../tutorials/custom_contracts) for +Check out the [Custom Contracts Tutorial](../../tutorials/custom_contracts/index.md) for a walk-through of how to set up listeners for the events from your smart contracts. diff --git a/docs/reference/types/_includes/data_description.md b/doc-site/docs/reference/types/_includes/data_description.md similarity index 95% rename from docs/reference/types/_includes/data_description.md rename to doc-site/docs/reference/types/_includes/data_description.md index e04d58266..928cb3349 100644 --- a/docs/reference/types/_includes/data_description.md +++ b/doc-site/docs/reference/types/_includes/data_description.md @@ -36,7 +36,7 @@ Use this system to enforce a set of common data types for exchange of data across your business network, and reduce the overhead of data verification\ required in the application/integration tier. -> More information in the [Datatype](./datatype.html) section +> More information in the [Datatype](./datatype.md) section ### Blob - binary data stored via the Data Exchange @@ -51,11 +51,10 @@ a set of extracted metadata from OCR processing of a PDF document. One special case is a filename for a document. This pattern is so common for file/document management scenarios, that special handling -is provided for it. If a JSON object is stored in `value`, and it has a property +is provided for it. If a JSON object is stored in `value`, and it has a property called `name`, then this value forms part of the data hash (as does every field in the `value`) and is stored in a separately indexed `blob.name` field. The upload REST API provides an `autometa` form field, which can be set to ask FireFly core to automatically set the `value` to contain the filename, size, and MIME type from the file upload. - diff --git a/docs/reference/types/_includes/datatype_description.md b/doc-site/docs/reference/types/_includes/datatype_description.md similarity index 100% rename from docs/reference/types/_includes/datatype_description.md rename to doc-site/docs/reference/types/_includes/datatype_description.md diff --git a/docs/reference/types/_includes/event_description.md b/doc-site/docs/reference/types/_includes/event_description.md similarity index 59% rename from docs/reference/types/_includes/event_description.md rename to doc-site/docs/reference/types/_includes/event_description.md index cd1b1e7d8..f5959f0a0 100644 --- a/docs/reference/types/_includes/event_description.md +++ b/doc-site/docs/reference/types/_includes/event_description.md @@ -1,8 +1,8 @@ Every Event emitted by FireFly shares a common structure. -> See [Events](../events.html) for a reference for how the overall event bus -in Hyperledger FireFly operates, and descriptions of all the sub-categories -of events. +> See [Events](../events.md) for a reference for how the overall event bus +> in Hyperledger FireFly operates, and descriptions of all the sub-categories +> of events. ### Sequence @@ -13,8 +13,8 @@ order that they are delivered to your application. ### Reference Events have a `reference` to the UUID of an object that is the subject of the event, -such as a detailed [Blockchain Event](./blockchainevent.html), or an off-chain -[Message](./message.html). +such as a detailed [Blockchain Event](./blockchainevent.md), or an off-chain +[Message](./message.md). When events are delivered to your application, the `reference` field is automatically retrieved and included in the JSON payload @@ -32,7 +32,7 @@ the `reference` field. ### Correlator For some event types, there is a secondary reference to an object that is -associated with the event. This is set in a `correlator` field on the +associated with the event. This is set in a `correlator` field on the Event, but is not automatically fetched. This field is primarily used for the `confirm` option on API calls to allow FireFly to determine when a request has succeeded/failed. @@ -44,14 +44,14 @@ the type of event. This is intended to be a property you would use to filter events to your application, or query all historical events associated with a given business data stream. -For example when you send a [Message](./message.html), you set the `topics` +For example when you send a [Message](./message.md), you set the `topics` you want that message to apply to, and FireFly ensures a consistent global order between all parties that receive that message. ### Transaction When actions are submitted by a FireFly node, they are performed -within a FireFly [Transaction](./transaction.html). The events that occur +within a FireFly [Transaction](./transaction.md). The events that occur as a direct result of that transaction, are tagged with the transaction ID so that they can be grouped together. @@ -72,29 +72,29 @@ Note that some events cannot be tagged with a Transaction ID: ### Reference, Topic and Correlator by Event Type -| Types | Reference | Topic | Correlator | -|---------------------------------------------|-------------------------------------------|-----------------------------|-------------------------| -| `transaction_submitted` | [Transaction](./transaction.html) | `transaction.type` | | -| `message_confirmed`
`message_rejected` | [Message](./message.html) | `message.header.topics[i]`* | `message.header.cid` | -| `token_pool_confirmed` | [TokenPool](./tokenpool.html) | `tokenPool.id` | | -| `token_pool_op_failed` | [Operation](./operation.html) | `tokenPool.id` | `tokenPool.id` | -| `token_transfer_confirmed` | [TokenTransfer](./tokentransfer.html) | `tokenPool.id` | | -| `token_transfer_op_failed` | [Operation](./operation.html) | `tokenPool.id` | `tokenTransfer.localId` | -| `token_approval_confirmed` | [TokenApproval](./tokenapproval.html) | `tokenPool.id` | | -| `token_approval_op_failed` | [Operation](./operation.html) | `tokenPool.id` | `tokenApproval.localId` | -| `namespace_confirmed` | [Namespace](./namespace.html) | `"ff_definition"` | | -| `datatype_confirmed` | [Datatype](./datatype.html) | `"ff_definition"` | | -| `identity_confirmed`
`identity_updated` | [Identity](./identity.html) | `"ff_definition"` | | -| `contract_interface_confirmed` | [FFI](./ffi.html) | `"ff_definition"` | | -| `contract_api_confirmed` | [ContractAPI](./contractapi.html) | `"ff_definition"` | | -| `blockchain_event_received` | [BlockchainEvent](./blockchainevent.html) | From listener ** | | -| `blockchain_invoke_op_succeeded` | [Operation](./operation.html) | | | -| `blockchain_invoke_op_failed` | [Operation](./operation.html) | | | -| `blockchain_contract_deploy_op_succeeded` | [Operation](./operation.html) | | | -| `blockchain_contract_deploy_op_failed` | [Operation](./operation.html) | | | - -> * A separate event is emitted for _each topic_ associated with a [Message](./message.html). - -> ** The topic for a blockchain event is inherited from the blockchain listener, -> allowing you to create multiple blockchain listeners that all deliver messages -> to your application on a single FireFly topic. +| Types | Reference | Topic | Correlator | +| ------------------------------------------- | --------------------------------------- | ---------------------------- | ----------------------- | +| `transaction_submitted` | [Transaction](./transaction.md) | `transaction.type` | | +| `message_confirmed`
`message_rejected` | [Message](./message.md) | `message.header.topics[i]`\* | `message.header.cid` | +| `token_pool_confirmed` | [TokenPool](./tokenpool.md) | `tokenPool.id` | | +| `token_pool_op_failed` | [Operation](./operation.md) | `tokenPool.id` | `tokenPool.id` | +| `token_transfer_confirmed` | [TokenTransfer](./tokentransfer.md) | `tokenPool.id` | | +| `token_transfer_op_failed` | [Operation](./operation.md) | `tokenPool.id` | `tokenTransfer.localId` | +| `token_approval_confirmed` | [TokenApproval](./tokenapproval.md) | `tokenPool.id` | | +| `token_approval_op_failed` | [Operation](./operation.md) | `tokenPool.id` | `tokenApproval.localId` | +| `namespace_confirmed` | [Namespace](./namespace.md) | `"ff_definition"` | | +| `datatype_confirmed` | [Datatype](./datatype.md) | `"ff_definition"` | | +| `identity_confirmed`
`identity_updated` | [Identity](./identity.md) | `"ff_definition"` | | +| `contract_interface_confirmed` | [FFI](./ffi.md) | `"ff_definition"` | | +| `contract_api_confirmed` | [ContractAPI](./contractapi.md) | `"ff_definition"` | | +| `blockchain_event_received` | [BlockchainEvent](./blockchainevent.md) | From listener \*\* | | +| `blockchain_invoke_op_succeeded` | [Operation](./operation.md) | | | +| `blockchain_invoke_op_failed` | [Operation](./operation.md) | | | +| `blockchain_contract_deploy_op_succeeded` | [Operation](./operation.md) | | | +| `blockchain_contract_deploy_op_failed` | [Operation](./operation.md) | | | + +> - A separate event is emitted for _each topic_ associated with a [Message](./message.md). + +> \*\* The topic for a blockchain event is inherited from the blockchain listener, +> allowing you to create multiple blockchain listeners that all deliver messages +> to your application on a single FireFly topic. diff --git a/docs/reference/types/_includes/ffbigint_description.md b/doc-site/docs/reference/types/_includes/ffbigint_description.md similarity index 100% rename from docs/reference/types/_includes/ffbigint_description.md rename to doc-site/docs/reference/types/_includes/ffbigint_description.md diff --git a/doc-site/docs/reference/types/_includes/ffi_description.md b/doc-site/docs/reference/types/_includes/ffi_description.md new file mode 100644 index 000000000..231ae80f9 --- /dev/null +++ b/doc-site/docs/reference/types/_includes/ffi_description.md @@ -0,0 +1 @@ +See [FireFly Interface Format](../firefly_interface_format.md) diff --git a/docs/reference/types/_includes/fftime_description.md b/doc-site/docs/reference/types/_includes/fftime_description.md similarity index 100% rename from docs/reference/types/_includes/fftime_description.md rename to doc-site/docs/reference/types/_includes/fftime_description.md diff --git a/docs/reference/types/_includes/group_description.md b/doc-site/docs/reference/types/_includes/group_description.md similarity index 95% rename from docs/reference/types/_includes/group_description.md rename to doc-site/docs/reference/types/_includes/group_description.md index d4bdb5166..4f1372170 100644 --- a/docs/reference/types/_includes/group_description.md +++ b/doc-site/docs/reference/types/_includes/group_description.md @@ -55,8 +55,7 @@ The key points are: hash for each member to determine if it is a message on a known group - even without the private data (which might arrive later) -> See [NextPin](./nextpin) for more information on the structure used for storing the next +> See [NextPin](./nextpin.md) for more information on the structure used for storing the next > expected masked context pin, for each member of the privacy group. -[![FireFly Privacy Model](../../images/firefly_data_privacy_model.jpg)](../../images/firefly_data_privacy_model.jpg) - +[![FireFly Privacy Model](../../images/firefly_data_privacy_model.jpg)](../../images/firefly_data_privacy_model.jpg) diff --git a/docs/reference/types/_includes/identity_description.md b/doc-site/docs/reference/types/_includes/identity_description.md similarity index 92% rename from docs/reference/types/_includes/identity_description.md rename to doc-site/docs/reference/types/_includes/identity_description.md index 95fe8b226..8cedcb04d 100644 --- a/docs/reference/types/_includes/identity_description.md +++ b/doc-site/docs/reference/types/_includes/identity_description.md @@ -3,6 +3,7 @@ way across a multi-party system through `claim` and `verification` system. > See [FIR-12](https://github.com/hyperledger/firefly-fir/pull/12) for evolution > that is happening to Hyperledger FireFly to allow: +> > - Private address books that are not shared with other participants > - Multiple address books backed by different chains, in the same node @@ -10,12 +11,12 @@ Root identities are registered with only a `claim` - which is a signed transaction from a particular blockchain account, to bind a DID with a `name` that is unique within the network, to that signing key. -The signing key then becomes a [Verifier](./verifier.html) for that identity. +The signing key then becomes a [Verifier](./verifier.md) for that identity. Using that key the root identity can be used to register a new FireFly node in the network, send and receive messages, and register child identities. When child identities are registered, a `claim` using a key that is going -to be the [Verifier](./verifier.html) for that child identity is required. +to be the [Verifier](./verifier.md) for that child identity is required. However, this is insufficient to establish that identity as a child identity of the parent. There must be an additional `verification` that references the `claim` (by UUID) using the key verifier of the parent identity. @@ -37,4 +38,3 @@ So an example FireFly DID for organization `abcd1234` is: You can also download a [DID Document](https://www.w3.org/TR/did-core/#dfn-did-documents) for a FireFly identity, which represents the verifiers and other information about that identity according to the JSON format in the DID standard. - diff --git a/docs/reference/types/_includes/jsonany_description.md b/doc-site/docs/reference/types/_includes/jsonany_description.md similarity index 100% rename from docs/reference/types/_includes/jsonany_description.md rename to doc-site/docs/reference/types/_includes/jsonany_description.md diff --git a/docs/reference/types/_includes/jsonobject_description.md b/doc-site/docs/reference/types/_includes/jsonobject_description.md similarity index 100% rename from docs/reference/types/_includes/jsonobject_description.md rename to doc-site/docs/reference/types/_includes/jsonobject_description.md diff --git a/docs/reference/types/_includes/message_description.md b/doc-site/docs/reference/types/_includes/message_description.md similarity index 96% rename from docs/reference/types/_includes/message_description.md rename to doc-site/docs/reference/types/_includes/message_description.md index a5670ad5f..8754e68b0 100644 --- a/docs/reference/types/_includes/message_description.md +++ b/doc-site/docs/reference/types/_includes/message_description.md @@ -2,7 +2,7 @@ Message is the envelope by which coordinated data exchange can happen between pa A message is made up of three sections: -1. The header - a set of metadata that determines how the message is ordered, who should receive it, and how they should process it +1. The header - a set of metadata that determines how the message is ordered, who should receive it, and how they should process it 2. The data - an array of data attachments 3. Status information - fields that are calculated independently by each node, and hence update as the message makes it way through the system @@ -18,14 +18,14 @@ The hash is a function of the header, and all of the data payloads. Calculated a - JSON data is serialized without whitespace to hash it. - The hashing algorithm is SHA-256 -Each node independently calculates the hash, and the hash is included in the manifest of the [Batch](./batch.html) by the +Each node independently calculates the hash, and the hash is included in the manifest of the [Batch](./batch.md) by the node that sends the message. Because the hash of that batch manifest is included in the blockchain transaction, a message transferred to a node that does not match the original message hash is rejected. ### Tag -The `header.tag` tells the processors of the message how it should be processed, and what data they should expect it to contain. +The `header.tag` tells the processors of the message how it should be processed, and what data they should expect it to contain. If you think of your decentralized application like a state machine, then you need to have a set of well defined transitions that can be performed between states. Each of these transitions that requires off-chain transfer of private data @@ -49,7 +49,7 @@ that there is a single source of truth for the order in which things happen. In a multi-party system with off-chain transfer of data as well as on-chain transfer of data, the two sets of data need to be coordinated together. The off-chain transfer might happen at different times, and is subject to the reliability -of the parties & network links involved in that off-chain communication. +of the parties & network links involved in that off-chain communication. A "stop the world" approach to handling a single piece of missing data is not practical for a high volume production business network. @@ -90,12 +90,12 @@ Some examples: - Agreeing to join two previously separate business transactions with ids `000001` and `000002`, by discarding business transaction `000001` as a duplicate - Specify `topics: ["000001","000002"]` on the special merge message, and then from that point onwards you would only need to specify `topics: ["000002"]`. -- Agreeing to join two previously separate entities with `id1` and `id2`, into a merged entity with `id3`. +- Agreeing to join two previously separate entities with `id1` and `id2`, into a merged entity with `id3`. - Specify `topics: ["id1","id2","id3"]` on the special merge message, and then from that point onwards you would only need to specify `topics: ["id3"]`. ### Transaction type -By default messages are pinned to the blockchain, within a [Batch](./batch.html). +By default messages are pinned to the blockchain, within a [Batch](./batch.md). For private messages, you can choose to disable this pinning by setting `header.txtype: "unpinned"`. @@ -103,7 +103,7 @@ Broadcast messages must be pinned to the blockchain. ### In-line data -When sending a message you can specify the array of [Data](./data.html) attachments in-line, as part of the same JSON payload. +When sending a message you can specify the array of [Data](./data.md) attachments in-line, as part of the same JSON payload. For example, a minimal broadcast message could be: @@ -116,6 +116,7 @@ For example, a minimal broadcast message could be: ``` When you send this message with `/api/v1/namespaces/{ns}/messages/broadcast`: + - The `header` will be initialized with the default values, including `txtype: "batch_pin"` - The `data[0]` entry will be stored as a Data resource - The message will be assembled into a batch and broadcast diff --git a/docs/reference/types/_includes/namespace_description.md b/doc-site/docs/reference/types/_includes/namespace_description.md similarity index 100% rename from docs/reference/types/_includes/namespace_description.md rename to doc-site/docs/reference/types/_includes/namespace_description.md diff --git a/docs/reference/types/_includes/nextpin_description.md b/doc-site/docs/reference/types/_includes/nextpin_description.md similarity index 85% rename from docs/reference/types/_includes/nextpin_description.md rename to doc-site/docs/reference/types/_includes/nextpin_description.md index a48b2199e..5d86f7cf2 100644 --- a/docs/reference/types/_includes/nextpin_description.md +++ b/doc-site/docs/reference/types/_includes/nextpin_description.md @@ -4,4 +4,4 @@ given "pin" for a message represents the next message for any member of the priv This allows every member to maintain a global order of transactions within a `topic` in a privacy group, without leaking the same hash between the messages that are communicated in that group. -> See [Group](./group) for more information on privacy groups. +> See [Group](./group.md) for more information on privacy groups. diff --git a/docs/reference/types/_includes/operation_description.md b/doc-site/docs/reference/types/_includes/operation_description.md similarity index 93% rename from docs/reference/types/_includes/operation_description.md rename to doc-site/docs/reference/types/_includes/operation_description.md index 2b1ed9d40..e55aa7069 100644 --- a/docs/reference/types/_includes/operation_description.md +++ b/doc-site/docs/reference/types/_includes/operation_description.md @@ -3,7 +3,7 @@ They are grouped into Transactions in order to accomplish a single logical task. The diagram below shows the different types of operation that are performed by each FireFly plugin type. The color coding (and numbers) map those different types of operation -to the [Transaction](./transaction.html) types that include those operations. +to the [Transaction](./transaction.md) types that include those operations. [![FireFly operations by transaction type](../../images/operations_by_transaction_type.jpg)](../../images/operations_by_transaction_type.jpg) diff --git a/docs/reference/types/_includes/operationwithdetail_description.md b/doc-site/docs/reference/types/_includes/operationwithdetail_description.md similarity index 100% rename from docs/reference/types/_includes/operationwithdetail_description.md rename to doc-site/docs/reference/types/_includes/operationwithdetail_description.md diff --git a/docs/reference/types/_includes/subscription_description.md b/doc-site/docs/reference/types/_includes/subscription_description.md similarity index 93% rename from docs/reference/types/_includes/subscription_description.md rename to doc-site/docs/reference/types/_includes/subscription_description.md index f28893f00..db2dab405 100644 --- a/docs/reference/types/_includes/subscription_description.md +++ b/doc-site/docs/reference/types/_includes/subscription_description.md @@ -1,4 +1,4 @@ -Each [Subscription](subscription.html#subscription) tracks delivery of events to a particular +Each [Subscription](#subscription) tracks delivery of events to a particular application, and allows FireFly to ensure that messages are delivered reliably to that application. @@ -75,13 +75,13 @@ FireFly has a simple protocol on top of WebSockets: 1. Each time you connect/reconnect you need to tell FireFly to start sending you events on a particular subscription. You can do this in two ways (described in detail below): - 1. Send a [WSStart](./wsstart.html) JSON payload - 2. Include a `namespace` and `name` query parameter in the URL when you - connect, along with query params for other fields of [WSStart](./wsstart.html) + 1. Send a [WSStart](./wsstart.md) JSON payload + 2. Include a `namespace` and `name` query parameter in the URL when you + connect, along with query params for other fields of [WSStart](./wsstart.md) 2. One you have started your subscription, each event flows from - the server, to your application as a JSON [Event](./event.html) payload -3. For each event you receive, you need to send a [WSAck](./wsack.html) payload. - - Unless you specified `autoack` in step (1) + the server, to your application as a JSON [Event](./event.md) payload +3. For each event you receive, you need to send a [WSAck](./wsack.md) payload. + - Unless you specified `autoack` in step (1) > The SDK libraries for FireFly help you ensure you send the `start` > payload each time your WebSocket reconnects. @@ -170,7 +170,7 @@ allowing you to customize your HTTP requests as follows: - Wait for a invocation of the back-end service, before acknowledging - To retry requests to your Webhook on a non-`2xx` HTTP status code or other error, you should enable and configure - [options.retry](../subscription.html#webhookretryoptions) + [options.retry](#webhookretryoptions) - The event is acknowledged once the request (with any retries), is completed - regardless of whether the outcome was a success or failure. - Use `fastack` to acknowledge against FireFly immediately and make multiple @@ -185,17 +185,14 @@ allowing you to customize your HTTP requests as follows: - Sets a `tag` in the reply message, per the configuration, or dynamically based on a field in the input request data. - -#### Batching events +#### Batching events Webhooks have the ability to batch events into a single HTTP request instead of sending an event per HTTP request. The interface will be a JSON array of events instead of a top level JSON object with a single event. The size of the batch will be set by the `readAhead` limit and an optional timeout can be specified to send the events when the batch hasn't filled. -To enable this set the following configuration under [SubscriptionOptions](../subscription.html#subscriptionoptions) +To enable this set the following configuration under [SubscriptionOptions](#subscriptionoptions) `batch` | Events are delivered in batches in an ordered array. The batch size is capped to the readAhead limit. The event payload is always an array even if there is a single event in the batch. Commonly used with Webhooks to allow events to be delivered and acknowledged in batches. | `bool` | `batchTimeout` | When batching is enabled, the optional timeout to send events even when the batch hasn't filled. Defaults to 2 seconds | `string` - **NOTE**: When batch is enabled, `withData` cannot be used as these may alter the HTTP request based on a single event and in batching it does not make sense for now. - diff --git a/docs/reference/types/_includes/tokenapproval_description.md b/doc-site/docs/reference/types/_includes/tokenapproval_description.md similarity index 100% rename from docs/reference/types/_includes/tokenapproval_description.md rename to doc-site/docs/reference/types/_includes/tokenapproval_description.md diff --git a/docs/reference/types/_includes/tokenpool_description.md b/doc-site/docs/reference/types/_includes/tokenpool_description.md similarity index 96% rename from docs/reference/types/_includes/tokenpool_description.md rename to doc-site/docs/reference/types/_includes/tokenpool_description.md index 5f4a4fb03..be528cd1d 100644 --- a/docs/reference/types/_includes/tokenpool_description.md +++ b/doc-site/docs/reference/types/_includes/tokenpool_description.md @@ -8,7 +8,7 @@ Check the documentation for your chosen connector implementation to see the deta for configuring a new Token Pool. Note that it is very common to use a Token Pool to teach Hyperledger FireFly about an -*existing token*, so that you can start interacting with a token that already exists. +_existing token_, so that you can start interacting with a token that already exists. ### Example token pool types @@ -25,3 +25,5 @@ Some examples of how the generic concept of a Token Pool maps to various well-de These are provided as examples only - a custom token connector could be backed by any token technology (Ethereum or otherwise) as long as it can support the basic operations described here (create pool, mint, burn, transfer). Other FireFly repos include a sample implementation of a token connector for [ERC-20 and ERC-721](https://github.com/hyperledger/firefly-tokens-erc20-erc721) as well as [ERC-1155](https://github.com/hyperledger/firefly-tokens-erc1155). + + diff --git a/docs/reference/types/_includes/tokentransfer_description.md b/doc-site/docs/reference/types/_includes/tokentransfer_description.md similarity index 100% rename from docs/reference/types/_includes/tokentransfer_description.md rename to doc-site/docs/reference/types/_includes/tokentransfer_description.md diff --git a/docs/reference/types/_includes/transaction_description.md b/doc-site/docs/reference/types/_includes/transaction_description.md similarity index 91% rename from docs/reference/types/_includes/transaction_description.md rename to doc-site/docs/reference/types/_includes/transaction_description.md index 70fc4e6c5..e69b0c166 100644 --- a/docs/reference/types/_includes/transaction_description.md +++ b/doc-site/docs/reference/types/_includes/transaction_description.md @@ -1,4 +1,4 @@ -FireFly Transactions are a grouping construct for a number of [Operations](./operation.html) and [Events](./event.html) +FireFly Transactions are a grouping construct for a number of [Operations](./operation.md) and [Events](./event.md) that need to complete or fail as unit. > FireFly Transactions are not themselves Blockchain transactions, but in many cases there is @@ -16,7 +16,7 @@ messages stored in IPFS to the blockchain. So there is a `Blockchain ID` for the transaction - as there is just one Blockchain transaction regardless of how many messages in the batch. There are operations for the submission of that transaction, and the upload of the data to IPFS. Then a corresponding `Blockchain Event Received` event for the detection -of the event from the blockchain smart contract when the transaction was mined, and a `Message Confirmed` +of the event from the blockchain smart contract when the transaction was mined, and a `Message Confirmed` event for each message in the batch (in this case 1). Then here the message was a special `Definition` message that advertised a new Contract API to all members of the network - so there is a `Contract API Confirmed` event as well. @@ -24,7 +24,7 @@ event as well. [![FireFly Transactions - Explorer View](../../images/firefly_transactions_explorer_view.png)](../../images/firefly_transactions_explorer_view.png) Each FireFly transaction has a UUID. This UUID is propagated through to all participants in a FireFly transaction. -For example in a [Token Transfer](./tokentransfer.html) that is coordinated with an off-chain private [Message](./message.html), +For example in a [Token Transfer](./tokentransfer.md) that is coordinated with an off-chain private [Message](./message.md), the transaction ID is propagated to all parties who are part of that transaction. So the same UUID can be used to find the transaction in the FireFly Explorer of any member who has access to the message. This is possible because hash-pinned off-chain data is associated with that on-chain transfer. diff --git a/docs/reference/types/_includes/uuid_description.md b/doc-site/docs/reference/types/_includes/uuid_description.md similarity index 100% rename from docs/reference/types/_includes/uuid_description.md rename to doc-site/docs/reference/types/_includes/uuid_description.md diff --git a/docs/reference/types/_includes/verifier_description.md b/doc-site/docs/reference/types/_includes/verifier_description.md similarity index 100% rename from docs/reference/types/_includes/verifier_description.md rename to doc-site/docs/reference/types/_includes/verifier_description.md diff --git a/docs/reference/types/_includes/wsack_description.md b/doc-site/docs/reference/types/_includes/wsack_description.md similarity index 83% rename from docs/reference/types/_includes/wsack_description.md rename to doc-site/docs/reference/types/_includes/wsack_description.md index b9ca8c53c..05379c89a 100644 --- a/docs/reference/types/_includes/wsack_description.md +++ b/doc-site/docs/reference/types/_includes/wsack_description.md @@ -1,6 +1,6 @@ An `ack` must be sent on a WebSocket for each event delivered to an application. -> Unless `autoack` is set in the [WSStart](./wsstart.html) payload/URL parameters to cause +> Unless `autoack` is set in the [WSStart](./wsstart.md) payload/URL parameters to cause > automatic acknowledgement. Your application should specify the `id` of each event that it acknowledges. @@ -11,5 +11,5 @@ application that has not been acknowledged is the one the `ack` is associated wi If multiple subscriptions are started on a WebSocket, then you need to specify the subscription `namespace`+`name` as part of each `ack`. -If you send an acknowledgement that cannot be correlated, then a [WSError](./wserror.html) +If you send an acknowledgement that cannot be correlated, then a [WSError](./wserror.md) payload will be sent to the application. diff --git a/docs/reference/types/_includes/wserror_description.md b/doc-site/docs/reference/types/_includes/wserror_description.md similarity index 100% rename from docs/reference/types/_includes/wserror_description.md rename to doc-site/docs/reference/types/_includes/wserror_description.md diff --git a/docs/reference/types/_includes/wsstart_description.md b/doc-site/docs/reference/types/_includes/wsstart_description.md similarity index 100% rename from docs/reference/types/_includes/wsstart_description.md rename to doc-site/docs/reference/types/_includes/wsstart_description.md diff --git a/docs/reference/types/batch.md b/doc-site/docs/reference/types/batch.md similarity index 78% rename from docs/reference/types/batch.md rename to doc-site/docs/reference/types/batch.md index 5958228da..b316b4bbe 100644 --- a/docs/reference/types/batch.md +++ b/doc-site/docs/reference/types/batch.md @@ -1,24 +1,7 @@ --- -layout: default title: Batch -parent: Core Resources -grand_parent: pages.reference -nav_order: 21 --- - -# Batch -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## Batch - -{% include_relative _includes/batch_description.md %} +{% include-markdown "./_includes/batch_description.md" %} ### Example @@ -48,12 +31,12 @@ nav_order: 21 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the batch | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the batch | [`UUID`](simpletypes.md#uuid) | | `type` | The type of the batch | `FFEnum`:
`"broadcast"`
`"private"` | | `namespace` | The namespace of the batch | `string` | -| `node` | The UUID of the node that generated the batch | [`UUID`](simpletypes#uuid) | +| `node` | The UUID of the node that generated the batch | [`UUID`](simpletypes.md#uuid) | | `group` | The privacy group the batch is sent to, for private batches | `Bytes32` | -| `created` | The time the batch was sealed | [`FFTime`](simpletypes#fftime) | +| `created` | The time the batch was sealed | [`FFTime`](simpletypes.md#fftime) | | `author` | The DID of identity of the submitter | `string` | | `key` | The on-chain signing key used to sign the transaction | `string` | | `hash` | The hash of the manifest of the batch | `Bytes32` | @@ -64,15 +47,15 @@ nav_order: 21 | Field Name | Description | Type | |------------|-------------|------| | `tx` | BatchPayload.tx | [`TransactionRef`](#transactionref) | -| `messages` | BatchPayload.messages | [`Message[]`](message#message) | -| `data` | BatchPayload.data | [`Data[]`](data#data) | +| `messages` | BatchPayload.messages | [`Message[]`](message.md#message) | +| `data` | BatchPayload.data | [`Data[]`](data.md#data) | ## TransactionRef | Field Name | Description | Type | |------------|-------------|------| | `type` | The type of the FireFly transaction | `FFEnum`: | -| `id` | The UUID of the FireFly transaction | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the FireFly transaction | [`UUID`](simpletypes.md#uuid) | diff --git a/docs/reference/types/blockchainevent.md b/doc-site/docs/reference/types/blockchainevent.md similarity index 87% rename from docs/reference/types/blockchainevent.md rename to doc-site/docs/reference/types/blockchainevent.md index 0edbd35cf..3128fb84a 100644 --- a/docs/reference/types/blockchainevent.md +++ b/doc-site/docs/reference/types/blockchainevent.md @@ -1,24 +1,7 @@ --- -layout: default title: BlockchainEvent -parent: Core Resources -grand_parent: pages.reference -nav_order: 5 --- - -# BlockchainEvent -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## BlockchainEvent - -{% include_relative _includes/blockchainevent_description.md %} +{% include-markdown "./_includes/blockchainevent_description.md" %} ### Example @@ -56,15 +39,15 @@ nav_order: 5 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID assigned to the event by FireFly | [`UUID`](simpletypes#uuid) | +| `id` | The UUID assigned to the event by FireFly | [`UUID`](simpletypes.md#uuid) | | `source` | The blockchain plugin or token service that detected the event | `string` | | `namespace` | The namespace of the listener that detected this blockchain event | `string` | | `name` | The name of the event in the blockchain smart contract | `string` | -| `listener` | The UUID of the listener that detected this event, or nil for built-in events in the system namespace | [`UUID`](simpletypes#uuid) | +| `listener` | The UUID of the listener that detected this event, or nil for built-in events in the system namespace | [`UUID`](simpletypes.md#uuid) | | `protocolId` | An alphanumerically sortable string that represents this event uniquely on the blockchain (convention for plugins is zero-padded values BLOCKNUMBER/TXN_INDEX/EVENT_INDEX) | `string` | -| `output` | The data output by the event, parsed to JSON according to the interface of the smart contract | [`JSONObject`](simpletypes#jsonobject) | -| `info` | Detailed blockchain specific information about the event, as generated by the blockchain connector | [`JSONObject`](simpletypes#jsonobject) | -| `timestamp` | The time allocated to this event by the blockchain. This is the block timestamp for most blockchain connectors | [`FFTime`](simpletypes#fftime) | +| `output` | The data output by the event, parsed to JSON according to the interface of the smart contract | [`JSONObject`](simpletypes.md#jsonobject) | +| `info` | Detailed blockchain specific information about the event, as generated by the blockchain connector | [`JSONObject`](simpletypes.md#jsonobject) | +| `timestamp` | The time allocated to this event by the blockchain. This is the block timestamp for most blockchain connectors | [`FFTime`](simpletypes.md#fftime) | | `tx` | If this blockchain event is coorelated to FireFly transaction such as a FireFly submitted token transfer, this field is set to the UUID of the FireFly transaction | [`BlockchainTransactionRef`](#blockchaintransactionref) | ## BlockchainTransactionRef @@ -72,7 +55,7 @@ nav_order: 5 | Field Name | Description | Type | |------------|-------------|------| | `type` | The type of the FireFly transaction | `FFEnum`: | -| `id` | The UUID of the FireFly transaction | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the FireFly transaction | [`UUID`](simpletypes.md#uuid) | | `blockchainId` | The blockchain transaction ID, in the format specific to the blockchain involved in the transaction. Not all FireFly transactions include a blockchain | `string` | diff --git a/docs/reference/types/contractapi.md b/doc-site/docs/reference/types/contractapi.md similarity index 82% rename from docs/reference/types/contractapi.md rename to doc-site/docs/reference/types/contractapi.md index 4672686f4..c4befcdcd 100644 --- a/docs/reference/types/contractapi.md +++ b/doc-site/docs/reference/types/contractapi.md @@ -1,24 +1,7 @@ --- -layout: default title: ContractAPI -parent: Core Resources -grand_parent: pages.reference -nav_order: 4 --- - -# ContractAPI -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## ContractAPI - -{% include_relative _includes/contractapi_description.md %} +{% include-markdown "./_includes/contractapi_description.md" %} ### Example @@ -47,13 +30,13 @@ nav_order: 4 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the contract API | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the contract API | [`UUID`](simpletypes.md#uuid) | | `namespace` | The namespace of the contract API | `string` | | `interface` | Reference to the FireFly Interface definition associated with the contract API | [`FFIReference`](#ffireference) | -| `location` | If this API is tied to an individual instance of a smart contract, this field can include a blockchain specific contract identifier. For example an Ethereum contract address, or a Fabric chaincode name and channel | [`JSONAny`](simpletypes#jsonany) | +| `location` | If this API is tied to an individual instance of a smart contract, this field can include a blockchain specific contract identifier. For example an Ethereum contract address, or a Fabric chaincode name and channel | [`JSONAny`](simpletypes.md#jsonany) | | `name` | The name that is used in the URL to access the API | `string` | | `networkName` | The published name of the API within the multiparty network | `string` | -| `message` | The UUID of the broadcast message that was used to publish this API to the network | [`UUID`](simpletypes#uuid) | +| `message` | The UUID of the broadcast message that was used to publish this API to the network | [`UUID`](simpletypes.md#uuid) | | `urls` | The URLs to use to access the API | [`ContractURLs`](#contracturls) | | `published` | Indicates if the API is published to other members of the multiparty network | `bool` | @@ -61,7 +44,7 @@ nav_order: 4 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the FireFly interface | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the FireFly interface | [`UUID`](simpletypes.md#uuid) | | `name` | The name of the FireFly interface | `string` | | `version` | The version of the FireFly interface | `string` | diff --git a/docs/reference/types/contractlistener.md b/doc-site/docs/reference/types/contractlistener.md similarity index 90% rename from docs/reference/types/contractlistener.md rename to doc-site/docs/reference/types/contractlistener.md index b15267712..9b73e1233 100644 --- a/docs/reference/types/contractlistener.md +++ b/doc-site/docs/reference/types/contractlistener.md @@ -1,24 +1,7 @@ --- -layout: default title: ContractListener -parent: Core Resources -grand_parent: pages.reference -nav_order: 10 --- - -# ContractListener -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## ContractListener - -{% include_relative _includes/contractlistener_description.md %} +{% include-markdown "./_includes/contractlistener_description.md" %} ### Example @@ -63,13 +46,13 @@ nav_order: 10 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the smart contract listener | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the smart contract listener | [`UUID`](simpletypes.md#uuid) | | `interface` | A reference to an existing FFI, containing pre-registered type information for the event | [`FFIReference`](#ffireference) | | `namespace` | The namespace of the listener, which defines the namespace of all blockchain events detected by this listener | `string` | | `name` | A descriptive name for the listener | `string` | | `backendId` | An ID assigned by the blockchain connector to this listener | `string` | -| `location` | A blockchain specific contract identifier. For example an Ethereum contract address, or a Fabric chaincode name and channel | [`JSONAny`](simpletypes#jsonany) | -| `created` | The creation time of the listener | [`FFTime`](simpletypes#fftime) | +| `location` | A blockchain specific contract identifier. For example an Ethereum contract address, or a Fabric chaincode name and channel | [`JSONAny`](simpletypes.md#jsonany) | +| `created` | The creation time of the listener | [`FFTime`](simpletypes.md#fftime) | | `event` | The definition of the event, either provided in-line when creating the listener, or extracted from the referenced FFI | [`FFISerializedEvent`](#ffiserializedevent) | | `signature` | The stringified signature of the event, as computed by the blockchain plugin | `string` | | `topic` | A topic to set on the FireFly event that is emitted each time a blockchain event is detected from the blockchain. Setting this topic on a number of listeners allows applications to easily subscribe to all events they need | `string` | @@ -79,7 +62,7 @@ nav_order: 10 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the FireFly interface | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the FireFly interface | [`UUID`](simpletypes.md#uuid) | | `name` | The name of the FireFly interface | `string` | | `version` | The version of the FireFly interface | `string` | @@ -91,14 +74,14 @@ nav_order: 10 | `name` | The name of the event | `string` | | `description` | A description of the smart contract event | `string` | | `params` | An array of event parameter/argument definitions | [`FFIParam[]`](#ffiparam) | -| `details` | Additional blockchain specific fields about this event from the original smart contract. Used by the blockchain plugin and for documentation generation. | [`JSONObject`](simpletypes#jsonobject) | +| `details` | Additional blockchain specific fields about this event from the original smart contract. Used by the blockchain plugin and for documentation generation. | [`JSONObject`](simpletypes.md#jsonobject) | ## FFIParam | Field Name | Description | Type | |------------|-------------|------| | `name` | The name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contract | `string` | -| `schema` | FireFly uses an extended subset of JSON Schema to describe parameters, similar to OpenAPI/Swagger. Converters are available for native blockchain interface definitions / type systems - such as an Ethereum ABI. See the documentation for more detail | [`JSONAny`](simpletypes#jsonany) | +| `schema` | FireFly uses an extended subset of JSON Schema to describe parameters, similar to OpenAPI/Swagger. Converters are available for native blockchain interface definitions / type systems - such as an Ethereum ABI. See the documentation for more detail | [`JSONAny`](simpletypes.md#jsonany) | diff --git a/docs/reference/types/data.md b/doc-site/docs/reference/types/data.md similarity index 87% rename from docs/reference/types/data.md rename to doc-site/docs/reference/types/data.md index f8bbedf81..d2bf626a8 100644 --- a/docs/reference/types/data.md +++ b/doc-site/docs/reference/types/data.md @@ -1,24 +1,7 @@ --- -layout: default title: Data -parent: Core Resources -grand_parent: pages.reference -nav_order: 17 --- - -# Data -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## Data - -{% include_relative _includes/data_description.md %} +{% include-markdown "./_includes/data_description.md" %} ### Example @@ -52,13 +35,13 @@ nav_order: 17 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the data resource | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the data resource | [`UUID`](simpletypes.md#uuid) | | `validator` | The data validator type | `FFEnum`: | | `namespace` | The namespace of the data resource | `string` | | `hash` | The hash of the data resource. Derived from the value and the hash of any binary blob attachment | `Bytes32` | -| `created` | The creation time of the data resource | [`FFTime`](simpletypes#fftime) | +| `created` | The creation time of the data resource | [`FFTime`](simpletypes.md#fftime) | | `datatype` | The optional datatype to use of validation of this data | [`DatatypeRef`](#datatyperef) | -| `value` | The value for the data, stored in the FireFly core database. Can be any JSON type - object, array, string, number or boolean. Can be combined with a binary blob attachment | [`JSONAny`](simpletypes#jsonany) | +| `value` | The value for the data, stored in the FireFly core database. Can be any JSON type - object, array, string, number or boolean. Can be combined with a binary blob attachment | [`JSONAny`](simpletypes.md#jsonany) | | `public` | If the JSON value has been published to shared storage, this field is the id of the data in the shared storage plugin (IPFS hash etc.) | `string` | | `blob` | An optional hash reference to a binary blob attachment | [`BlobRef`](#blobref) | diff --git a/docs/reference/types/datatype.md b/doc-site/docs/reference/types/datatype.md similarity index 81% rename from docs/reference/types/datatype.md rename to doc-site/docs/reference/types/datatype.md index 5497bd50b..75cfe8e4c 100644 --- a/docs/reference/types/datatype.md +++ b/doc-site/docs/reference/types/datatype.md @@ -1,24 +1,7 @@ --- -layout: default title: Datatype -parent: Core Resources -grand_parent: pages.reference -nav_order: 18 --- - -# Datatype -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## Datatype - -{% include_relative _includes/datatype_description.md %} +{% include-markdown "./_includes/datatype_description.md" %} ### Example @@ -56,13 +39,13 @@ nav_order: 18 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the datatype | [`UUID`](simpletypes#uuid) | -| `message` | The UUID of the broadcast message that was used to publish this datatype to the network | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the datatype | [`UUID`](simpletypes.md#uuid) | +| `message` | The UUID of the broadcast message that was used to publish this datatype to the network | [`UUID`](simpletypes.md#uuid) | | `validator` | The validator that should be used to verify this datatype | `FFEnum`:
`"json"`
`"none"`
`"definition"` | | `namespace` | The namespace of the datatype. Data resources can only be created referencing datatypes in the same namespace | `string` | | `name` | The name of the datatype | `string` | | `version` | The version of the datatype. Multiple versions can exist with the same name. Use of semantic versioning is encourages, such as v1.0.1 | `string` | | `hash` | The hash of the value, such as the JSON schema. Allows all parties to be confident they have the exact same rules for verifying data created against a datatype | `Bytes32` | -| `created` | The time the datatype was created | [`FFTime`](simpletypes#fftime) | -| `value` | The definition of the datatype, in the syntax supported by the validator (such as a JSON Schema definition) | [`JSONAny`](simpletypes#jsonany) | +| `created` | The time the datatype was created | [`FFTime`](simpletypes.md#fftime) | +| `value` | The definition of the datatype, in the syntax supported by the validator (such as a JSON Schema definition) | [`JSONAny`](simpletypes.md#jsonany) | diff --git a/docs/reference/types/event.md b/doc-site/docs/reference/types/event.md similarity index 86% rename from docs/reference/types/event.md rename to doc-site/docs/reference/types/event.md index 6fbc38dbd..40a274690 100644 --- a/docs/reference/types/event.md +++ b/doc-site/docs/reference/types/event.md @@ -1,24 +1,7 @@ --- -layout: default title: Event -parent: Core Resources -grand_parent: pages.reference -nav_order: 2 --- - -# Event -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## Event - -{% include_relative _includes/event_description.md %} +{% include-markdown "./_includes/event_description.md" %} ### Example @@ -39,13 +22,13 @@ nav_order: 2 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID assigned to this event by your local FireFly node | [`UUID`](simpletypes#uuid) | +| `id` | The UUID assigned to this event by your local FireFly node | [`UUID`](simpletypes.md#uuid) | | `sequence` | A sequence indicating the order in which events are delivered to your application. Assure to be unique per event in your local FireFly database (unlike the created timestamp) | `int64` | | `type` | All interesting activity in FireFly is emitted as a FireFly event, of a given type. The 'type' combined with the 'reference' can be used to determine how to process the event within your application | `FFEnum`:
`"transaction_submitted"`
`"message_confirmed"`
`"message_rejected"`
`"datatype_confirmed"`
`"identity_confirmed"`
`"identity_updated"`
`"token_pool_confirmed"`
`"token_pool_op_failed"`
`"token_transfer_confirmed"`
`"token_transfer_op_failed"`
`"token_approval_confirmed"`
`"token_approval_op_failed"`
`"contract_interface_confirmed"`
`"contract_api_confirmed"`
`"blockchain_event_received"`
`"blockchain_invoke_op_succeeded"`
`"blockchain_invoke_op_failed"`
`"blockchain_contract_deploy_op_succeeded"`
`"blockchain_contract_deploy_op_failed"` | | `namespace` | The namespace of the event. Your application must subscribe to events within a namespace | `string` | -| `reference` | The UUID of an resource that is the subject of this event. The event type determines what type of resource is referenced, and whether this field might be unset | [`UUID`](simpletypes#uuid) | -| `correlator` | For message events, this is the 'header.cid' field from the referenced message. For certain other event types, a secondary object is referenced such as a token pool | [`UUID`](simpletypes#uuid) | -| `tx` | The UUID of a transaction that is event is part of. Not all events are part of a transaction | [`UUID`](simpletypes#uuid) | +| `reference` | The UUID of an resource that is the subject of this event. The event type determines what type of resource is referenced, and whether this field might be unset | [`UUID`](simpletypes.md#uuid) | +| `correlator` | For message events, this is the 'header.cid' field from the referenced message. For certain other event types, a secondary object is referenced such as a token pool | [`UUID`](simpletypes.md#uuid) | +| `tx` | The UUID of a transaction that is event is part of. Not all events are part of a transaction | [`UUID`](simpletypes.md#uuid) | | `topic` | A stream of information this event relates to. For message confirmation events, a separate event is emitted for each topic in the message. For blockchain events, the listener specifies the topic. Rules exist for how the topic is set for other event types | `string` | -| `created` | The time the event was emitted. Not guaranteed to be unique, or to increase between events in the same order as the final sequence events are delivered to your application. As such, the 'sequence' field should be used instead of the 'created' field for querying events in the exact order they are delivered to applications | [`FFTime`](simpletypes#fftime) | +| `created` | The time the event was emitted. Not guaranteed to be unique, or to increase between events in the same order as the final sequence events are delivered to your application. As such, the 'sequence' field should be used instead of the 'created' field for querying events in the exact order they are delivered to applications | [`FFTime`](simpletypes.md#fftime) | diff --git a/docs/reference/types/ffi.md b/doc-site/docs/reference/types/ffi.md similarity index 91% rename from docs/reference/types/ffi.md rename to doc-site/docs/reference/types/ffi.md index 01159395c..1d5b4692e 100644 --- a/docs/reference/types/ffi.md +++ b/doc-site/docs/reference/types/ffi.md @@ -1,24 +1,7 @@ --- -layout: default title: FFI -parent: Core Resources -grand_parent: pages.reference -nav_order: 9 --- - -# FFI -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## FFI - -{% include_relative _includes/ffi_description.md %} +{% include-markdown "./_includes/ffi_description.md" %} ### Example @@ -118,8 +101,8 @@ nav_order: 9 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the FireFly interface (FFI) smart contract definition | [`UUID`](simpletypes#uuid) | -| `message` | The UUID of the broadcast message that was used to publish this FFI to the network | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the FireFly interface (FFI) smart contract definition | [`UUID`](simpletypes.md#uuid) | +| `message` | The UUID of the broadcast message that was used to publish this FFI to the network | [`UUID`](simpletypes.md#uuid) | | `namespace` | The namespace of the FFI | `string` | | `name` | The name of the FFI - usually matching the smart contract name | `string` | | `networkName` | The published name of the FFI within the multiparty network | `string` | @@ -134,22 +117,22 @@ nav_order: 9 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the FFI method definition | [`UUID`](simpletypes#uuid) | -| `interface` | The UUID of the FFI smart contract definition that this method is part of | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the FFI method definition | [`UUID`](simpletypes.md#uuid) | +| `interface` | The UUID of the FFI smart contract definition that this method is part of | [`UUID`](simpletypes.md#uuid) | | `name` | The name of the method | `string` | | `namespace` | The namespace of the FFI | `string` | | `pathname` | The unique name allocated to this method within the FFI for use on URL paths. Supports contracts that have multiple method overrides with the same name | `string` | | `description` | A description of the smart contract method | `string` | | `params` | An array of method parameter/argument definitions | [`FFIParam[]`](#ffiparam) | | `returns` | An array of method return definitions | [`FFIParam[]`](#ffiparam) | -| `details` | Additional blockchain specific fields about this method from the original smart contract. Used by the blockchain plugin and for documentation generation. | [`JSONObject`](simpletypes#jsonobject) | +| `details` | Additional blockchain specific fields about this method from the original smart contract. Used by the blockchain plugin and for documentation generation. | [`JSONObject`](simpletypes.md#jsonobject) | ## FFIParam | Field Name | Description | Type | |------------|-------------|------| | `name` | The name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contract | `string` | -| `schema` | FireFly uses an extended subset of JSON Schema to describe parameters, similar to OpenAPI/Swagger. Converters are available for native blockchain interface definitions / type systems - such as an Ethereum ABI. See the documentation for more detail | [`JSONAny`](simpletypes#jsonany) | +| `schema` | FireFly uses an extended subset of JSON Schema to describe parameters, similar to OpenAPI/Swagger. Converters are available for native blockchain interface definitions / type systems - such as an Ethereum ABI. See the documentation for more detail | [`JSONAny`](simpletypes.md#jsonany) | @@ -157,22 +140,22 @@ nav_order: 9 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the FFI event definition | [`UUID`](simpletypes#uuid) | -| `interface` | The UUID of the FFI smart contract definition that this event is part of | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the FFI event definition | [`UUID`](simpletypes.md#uuid) | +| `interface` | The UUID of the FFI smart contract definition that this event is part of | [`UUID`](simpletypes.md#uuid) | | `namespace` | The namespace of the FFI | `string` | | `pathname` | The unique name allocated to this event within the FFI for use on URL paths. Supports contracts that have multiple event overrides with the same name | `string` | | `signature` | The stringified signature of the event, as computed by the blockchain plugin | `string` | | `name` | The name of the event | `string` | | `description` | A description of the smart contract event | `string` | | `params` | An array of event parameter/argument definitions | [`FFIParam[]`](#ffiparam) | -| `details` | Additional blockchain specific fields about this event from the original smart contract. Used by the blockchain plugin and for documentation generation. | [`JSONObject`](simpletypes#jsonobject) | +| `details` | Additional blockchain specific fields about this event from the original smart contract. Used by the blockchain plugin and for documentation generation. | [`JSONObject`](simpletypes.md#jsonobject) | ## FFIParam | Field Name | Description | Type | |------------|-------------|------| | `name` | The name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contract | `string` | -| `schema` | FireFly uses an extended subset of JSON Schema to describe parameters, similar to OpenAPI/Swagger. Converters are available for native blockchain interface definitions / type systems - such as an Ethereum ABI. See the documentation for more detail | [`JSONAny`](simpletypes#jsonany) | +| `schema` | FireFly uses an extended subset of JSON Schema to describe parameters, similar to OpenAPI/Swagger. Converters are available for native blockchain interface definitions / type systems - such as an Ethereum ABI. See the documentation for more detail | [`JSONAny`](simpletypes.md#jsonany) | @@ -180,8 +163,8 @@ nav_order: 9 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the FFI error definition | [`UUID`](simpletypes#uuid) | -| `interface` | The UUID of the FFI smart contract definition that this error is part of | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the FFI error definition | [`UUID`](simpletypes.md#uuid) | +| `interface` | The UUID of the FFI smart contract definition that this error is part of | [`UUID`](simpletypes.md#uuid) | | `namespace` | The namespace of the FFI | `string` | | `pathname` | The unique name allocated to this error within the FFI for use on URL paths | `string` | | `signature` | The stringified signature of the error, as computed by the blockchain plugin | `string` | @@ -194,7 +177,7 @@ nav_order: 9 | Field Name | Description | Type | |------------|-------------|------| | `name` | The name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contract | `string` | -| `schema` | FireFly uses an extended subset of JSON Schema to describe parameters, similar to OpenAPI/Swagger. Converters are available for native blockchain interface definitions / type systems - such as an Ethereum ABI. See the documentation for more detail | [`JSONAny`](simpletypes#jsonany) | +| `schema` | FireFly uses an extended subset of JSON Schema to describe parameters, similar to OpenAPI/Swagger. Converters are available for native blockchain interface definitions / type systems - such as an Ethereum ABI. See the documentation for more detail | [`JSONAny`](simpletypes.md#jsonany) | diff --git a/docs/reference/types/group.md b/doc-site/docs/reference/types/group.md similarity index 78% rename from docs/reference/types/group.md rename to doc-site/docs/reference/types/group.md index 461ea5743..671bb596c 100644 --- a/docs/reference/types/group.md +++ b/doc-site/docs/reference/types/group.md @@ -1,24 +1,7 @@ --- -layout: default title: Group -parent: Core Resources -grand_parent: pages.reference -nav_order: 19 --- - -# Group -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## Group - -{% include_relative _includes/group_description.md %} +{% include-markdown "./_includes/group_description.md" %} ### Example @@ -51,15 +34,15 @@ nav_order: 19 | `name` | The optional name of the group, allowing multiple unique groups to exist with the same list of recipients | `string` | | `members` | The list of members in this privacy group | [`Member[]`](#member) | | `localNamespace` | The local namespace of the group | `string` | -| `message` | The message used to broadcast this group privately to the members | [`UUID`](simpletypes#uuid) | +| `message` | The message used to broadcast this group privately to the members | [`UUID`](simpletypes.md#uuid) | | `hash` | The identifier hash of this group. Derived from the name and group members | `Bytes32` | -| `created` | The time when the group was first used to send a message in the network | [`FFTime`](simpletypes#fftime) | +| `created` | The time when the group was first used to send a message in the network | [`FFTime`](simpletypes.md#fftime) | ## Member | Field Name | Description | Type | |------------|-------------|------| | `identity` | The DID of the group member | `string` | -| `node` | The UUID of the node that receives a copy of the off-chain message for the identity | [`UUID`](simpletypes#uuid) | +| `node` | The UUID of the node that receives a copy of the off-chain message for the identity | [`UUID`](simpletypes.md#uuid) | diff --git a/docs/reference/types/identity.md b/doc-site/docs/reference/types/identity.md similarity index 77% rename from docs/reference/types/identity.md rename to doc-site/docs/reference/types/identity.md index 7a9e18693..348d77d86 100644 --- a/docs/reference/types/identity.md +++ b/doc-site/docs/reference/types/identity.md @@ -1,24 +1,7 @@ --- -layout: default title: Identity -parent: Core Resources -grand_parent: pages.reference -nav_order: 14 --- - -# Identity -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## Identity - -{% include_relative _includes/identity_description.md %} +{% include-markdown "./_includes/identity_description.md" %} ### Example @@ -43,24 +26,24 @@ nav_order: 14 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the identity | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the identity | [`UUID`](simpletypes.md#uuid) | | `did` | The DID of the identity. Unique across namespaces within a FireFly network | `string` | | `type` | The type of the identity | `FFEnum`:
`"org"`
`"node"`
`"custom"` | -| `parent` | The UUID of the parent identity. Unset for root organization identities | [`UUID`](simpletypes#uuid) | +| `parent` | The UUID of the parent identity. Unset for root organization identities | [`UUID`](simpletypes.md#uuid) | | `namespace` | The namespace of the identity. Organization and node identities are always defined in the ff_system namespace | `string` | | `name` | The name of the identity. The name must be unique within the type and namespace | `string` | | `description` | A description of the identity. Part of the updatable profile information of an identity | `string` | -| `profile` | A set of metadata for the identity. Part of the updatable profile information of an identity | [`JSONObject`](simpletypes#jsonobject) | +| `profile` | A set of metadata for the identity. Part of the updatable profile information of an identity | [`JSONObject`](simpletypes.md#jsonobject) | | `messages` | References to the broadcast messages that established this identity and proved ownership of the associated verifiers (keys) | [`IdentityMessages`](#identitymessages) | -| `created` | The creation time of the identity | [`FFTime`](simpletypes#fftime) | -| `updated` | The last update time of the identity profile | [`FFTime`](simpletypes#fftime) | +| `created` | The creation time of the identity | [`FFTime`](simpletypes.md#fftime) | +| `updated` | The last update time of the identity profile | [`FFTime`](simpletypes.md#fftime) | ## IdentityMessages | Field Name | Description | Type | |------------|-------------|------| -| `claim` | The UUID of claim message | [`UUID`](simpletypes#uuid) | -| `verification` | The UUID of claim message. Unset for root organization identities | [`UUID`](simpletypes#uuid) | -| `update` | The UUID of the most recently applied update message. Unset if no updates have been confirmed | [`UUID`](simpletypes#uuid) | +| `claim` | The UUID of claim message | [`UUID`](simpletypes.md#uuid) | +| `verification` | The UUID of claim message. Unset for root organization identities | [`UUID`](simpletypes.md#uuid) | +| `update` | The UUID of the most recently applied update message. Unset if no updates have been confirmed | [`UUID`](simpletypes.md#uuid) | diff --git a/docs/reference/types/message.md b/doc-site/docs/reference/types/message.md similarity index 89% rename from docs/reference/types/message.md rename to doc-site/docs/reference/types/message.md index 444616871..dcb90bfda 100644 --- a/docs/reference/types/message.md +++ b/doc-site/docs/reference/types/message.md @@ -1,24 +1,7 @@ --- -layout: default title: Message -parent: Core Resources -grand_parent: pages.reference -nav_order: 16 --- - -# Message -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## Message - -{% include_relative _includes/message_description.md %} +{% include-markdown "./_includes/message_description.md" %} ### Example @@ -59,10 +42,10 @@ nav_order: 16 | `header` | The message header contains all fields that are used to build the message hash | [`MessageHeader`](#messageheader) | | `localNamespace` | The local namespace of the message | `string` | | `hash` | The hash of the message. Derived from the header, which includes the data hash | `Bytes32` | -| `batch` | The UUID of the batch in which the message was pinned/transferred | [`UUID`](simpletypes#uuid) | -| `txid` | The ID of the transaction used to order/deliver this message | [`UUID`](simpletypes#uuid) | +| `batch` | The UUID of the batch in which the message was pinned/transferred | [`UUID`](simpletypes.md#uuid) | +| `txid` | The ID of the transaction used to order/deliver this message | [`UUID`](simpletypes.md#uuid) | | `state` | The current state of the message | `FFEnum`:
`"staged"`
`"ready"`
`"sent"`
`"pending"`
`"confirmed"`
`"rejected"`
`"cancelled"` | -| `confirmed` | The timestamp of when the message was confirmed/rejected | [`FFTime`](simpletypes#fftime) | +| `confirmed` | The timestamp of when the message was confirmed/rejected | [`FFTime`](simpletypes.md#fftime) | | `rejectReason` | If a message was rejected, provides details on the rejection reason | `string` | | `data` | The list of data elements attached to the message | [`DataRef[]`](#dataref) | | `pins` | For private messages, a unique pin hash:nonce is assigned for each topic | `string[]` | @@ -72,13 +55,13 @@ nav_order: 16 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the message. Unique to each message | [`UUID`](simpletypes#uuid) | -| `cid` | The correlation ID of the message. Set this when a message is a response to another message | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the message. Unique to each message | [`UUID`](simpletypes.md#uuid) | +| `cid` | The correlation ID of the message. Set this when a message is a response to another message | [`UUID`](simpletypes.md#uuid) | | `type` | The type of the message | `FFEnum`:
`"definition"`
`"broadcast"`
`"private"`
`"groupinit"`
`"transfer_broadcast"`
`"transfer_private"`
`"approval_broadcast"`
`"approval_private"` | | `txtype` | The type of transaction used to order/deliver this message | `FFEnum`:
`"none"`
`"unpinned"`
`"batch_pin"`
`"network_action"`
`"token_pool"`
`"token_transfer"`
`"contract_deploy"`
`"contract_invoke"`
`"contract_invoke_pin"`
`"token_approval"`
`"data_publish"` | | `author` | The DID of identity of the submitter | `string` | | `key` | The on-chain signing key used to sign the transaction | `string` | -| `created` | The creation time of the message | [`FFTime`](simpletypes#fftime) | +| `created` | The creation time of the message | [`FFTime`](simpletypes.md#fftime) | | `namespace` | The namespace of the message within the multiparty network | `string` | | `topics` | A message topic associates this message with an ordered stream of data. A custom topic should be assigned - using the default topic is discouraged | `string[]` | | `tag` | The message tag indicates the purpose of the message to the applications that process it | `string` | @@ -90,7 +73,7 @@ nav_order: 16 | Field Name | Description | Type | |------------|-------------|------| | `type` | The type of the FireFly transaction | `FFEnum`: | -| `id` | The UUID of the FireFly transaction | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the FireFly transaction | [`UUID`](simpletypes.md#uuid) | @@ -98,7 +81,7 @@ nav_order: 16 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the referenced data resource | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the referenced data resource | [`UUID`](simpletypes.md#uuid) | | `hash` | The hash of the referenced data | `Bytes32` | diff --git a/docs/reference/types/namespace.md b/doc-site/docs/reference/types/namespace.md similarity index 67% rename from docs/reference/types/namespace.md rename to doc-site/docs/reference/types/namespace.md index 6d1ed31e3..fb77b2ca0 100644 --- a/docs/reference/types/namespace.md +++ b/doc-site/docs/reference/types/namespace.md @@ -1,24 +1,7 @@ --- -layout: default title: Namespace -parent: Core Resources -grand_parent: pages.reference -nav_order: 22 --- - -# Namespace -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## Namespace - -{% include_relative _includes/namespace_description.md %} +{% include-markdown "./_includes/namespace_description.md" %} ### Example @@ -38,5 +21,5 @@ nav_order: 22 | `name` | The local namespace name | `string` | | `networkName` | The shared namespace name within the multiparty network | `string` | | `description` | A description of the namespace | `string` | -| `created` | The time the namespace was created | [`FFTime`](simpletypes#fftime) | +| `created` | The time the namespace was created | [`FFTime`](simpletypes.md#fftime) | diff --git a/docs/reference/types/nextpin.md b/doc-site/docs/reference/types/nextpin.md similarity index 80% rename from docs/reference/types/nextpin.md rename to doc-site/docs/reference/types/nextpin.md index 5bc591320..9bb49091e 100644 --- a/docs/reference/types/nextpin.md +++ b/doc-site/docs/reference/types/nextpin.md @@ -1,24 +1,7 @@ --- -layout: default title: NextPin -parent: Core Resources -grand_parent: pages.reference -nav_order: 20 --- - -# NextPin -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## NextPin - -{% include_relative _includes/nextpin_description.md %} +{% include-markdown "./_includes/nextpin_description.md" %} ### Example diff --git a/docs/reference/types/operation.md b/doc-site/docs/reference/types/operation.md similarity index 78% rename from docs/reference/types/operation.md rename to doc-site/docs/reference/types/operation.md index d9dc7d54e..6e543a702 100644 --- a/docs/reference/types/operation.md +++ b/doc-site/docs/reference/types/operation.md @@ -1,24 +1,7 @@ --- -layout: default title: Operation -parent: Core Resources -grand_parent: pages.reference -nav_order: 7 --- - -# Operation -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## Operation - -{% include_relative _includes/operation_description.md %} +{% include-markdown "./_includes/operation_description.md" %} ### Example @@ -44,16 +27,16 @@ nav_order: 7 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the operation | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the operation | [`UUID`](simpletypes.md#uuid) | | `namespace` | The namespace of the operation | `string` | -| `tx` | The UUID of the FireFly transaction the operation is part of | [`UUID`](simpletypes#uuid) | +| `tx` | The UUID of the FireFly transaction the operation is part of | [`UUID`](simpletypes.md#uuid) | | `type` | The type of the operation | `FFEnum`:
`"blockchain_pin_batch"`
`"blockchain_network_action"`
`"blockchain_deploy"`
`"blockchain_invoke"`
`"sharedstorage_upload_batch"`
`"sharedstorage_upload_blob"`
`"sharedstorage_upload_value"`
`"sharedstorage_download_batch"`
`"sharedstorage_download_blob"`
`"dataexchange_send_batch"`
`"dataexchange_send_blob"`
`"token_create_pool"`
`"token_activate_pool"`
`"token_transfer"`
`"token_approval"` | | `status` | The current status of the operation | `OpStatus` | | `plugin` | The plugin responsible for performing the operation | `string` | -| `input` | The input to this operation | [`JSONObject`](simpletypes#jsonobject) | -| `output` | Any output reported back from the plugin for this operation | [`JSONObject`](simpletypes#jsonobject) | +| `input` | The input to this operation | [`JSONObject`](simpletypes.md#jsonobject) | +| `output` | Any output reported back from the plugin for this operation | [`JSONObject`](simpletypes.md#jsonobject) | | `error` | Any error reported back from the plugin for this operation | `string` | -| `created` | The time the operation was created | [`FFTime`](simpletypes#fftime) | -| `updated` | The last update time of the operation | [`FFTime`](simpletypes#fftime) | -| `retry` | If this operation was initiated as a retry to a previous operation, this field points to the UUID of the operation being retried | [`UUID`](simpletypes#uuid) | +| `created` | The time the operation was created | [`FFTime`](simpletypes.md#fftime) | +| `updated` | The last update time of the operation | [`FFTime`](simpletypes.md#fftime) | +| `retry` | If this operation was initiated as a retry to a previous operation, this field points to the UUID of the operation being retried | [`UUID`](simpletypes.md#uuid) | diff --git a/docs/reference/types/operationwithdetail.md b/doc-site/docs/reference/types/operationwithdetail.md similarity index 90% rename from docs/reference/types/operationwithdetail.md rename to doc-site/docs/reference/types/operationwithdetail.md index 0897bd292..59c1e11ae 100644 --- a/docs/reference/types/operationwithdetail.md +++ b/doc-site/docs/reference/types/operationwithdetail.md @@ -1,24 +1,7 @@ --- -layout: default title: OperationWithDetail -parent: Core Resources -grand_parent: pages.reference -nav_order: 8 --- - -# OperationWithDetail -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## OperationWithDetail - -{% include_relative _includes/operationwithdetail_description.md %} +{% include-markdown "./_includes/operationwithdetail_description.md" %} ### Example @@ -136,17 +119,17 @@ nav_order: 8 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the operation | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the operation | [`UUID`](simpletypes.md#uuid) | | `namespace` | The namespace of the operation | `string` | -| `tx` | The UUID of the FireFly transaction the operation is part of | [`UUID`](simpletypes#uuid) | +| `tx` | The UUID of the FireFly transaction the operation is part of | [`UUID`](simpletypes.md#uuid) | | `type` | The type of the operation | `FFEnum`:
`"blockchain_pin_batch"`
`"blockchain_network_action"`
`"blockchain_deploy"`
`"blockchain_invoke"`
`"sharedstorage_upload_batch"`
`"sharedstorage_upload_blob"`
`"sharedstorage_upload_value"`
`"sharedstorage_download_batch"`
`"sharedstorage_download_blob"`
`"dataexchange_send_batch"`
`"dataexchange_send_blob"`
`"token_create_pool"`
`"token_activate_pool"`
`"token_transfer"`
`"token_approval"` | | `status` | The current status of the operation | `OpStatus` | | `plugin` | The plugin responsible for performing the operation | `string` | -| `input` | The input to this operation | [`JSONObject`](simpletypes#jsonobject) | -| `output` | Any output reported back from the plugin for this operation | [`JSONObject`](simpletypes#jsonobject) | +| `input` | The input to this operation | [`JSONObject`](simpletypes.md#jsonobject) | +| `output` | Any output reported back from the plugin for this operation | [`JSONObject`](simpletypes.md#jsonobject) | | `error` | Any error reported back from the plugin for this operation | `string` | -| `created` | The time the operation was created | [`FFTime`](simpletypes#fftime) | -| `updated` | The last update time of the operation | [`FFTime`](simpletypes#fftime) | -| `retry` | If this operation was initiated as a retry to a previous operation, this field points to the UUID of the operation being retried | [`UUID`](simpletypes#uuid) | +| `created` | The time the operation was created | [`FFTime`](simpletypes.md#fftime) | +| `updated` | The last update time of the operation | [`FFTime`](simpletypes.md#fftime) | +| `retry` | If this operation was initiated as a retry to a previous operation, this field points to the UUID of the operation being retried | [`UUID`](simpletypes.md#uuid) | | `detail` | Additional detailed information about an operation provided by the connector | `` | diff --git a/doc-site/docs/reference/types/simpletypes.md b/doc-site/docs/reference/types/simpletypes.md new file mode 100644 index 000000000..045c3da4f --- /dev/null +++ b/doc-site/docs/reference/types/simpletypes.md @@ -0,0 +1,23 @@ +--- +title: Simple Types +--- +## UUID + +{% include-markdown "./_includes/uuid_description.md" %} + +## FFTime + +{% include-markdown "./_includes/fftime_description.md" %} + +## FFBigInt + +{% include-markdown "./_includes/ffbigint_description.md" %} + +## JSONAny + +{% include-markdown "./_includes/jsonany_description.md" %} + +## JSONObject + +{% include-markdown "./_includes/jsonobject_description.md" %} + diff --git a/docs/reference/types/subscription.md b/doc-site/docs/reference/types/subscription.md similarity index 96% rename from docs/reference/types/subscription.md rename to doc-site/docs/reference/types/subscription.md index 584fb45c5..d6a8767cc 100644 --- a/docs/reference/types/subscription.md +++ b/doc-site/docs/reference/types/subscription.md @@ -1,24 +1,7 @@ --- -layout: default title: Subscription -parent: Core Resources -grand_parent: pages.reference -nav_order: 3 --- - -# Subscription -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## Subscription - -{% include_relative _includes/subscription_description.md %} +{% include-markdown "./_includes/subscription_description.md" %} ### Example @@ -49,15 +32,15 @@ nav_order: 3 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the subscription | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the subscription | [`UUID`](simpletypes.md#uuid) | | `namespace` | The namespace of the subscription. A subscription will only receive events generated in the namespace of the subscription | `string` | | `name` | The name of the subscription. The application specifies this name when it connects, in order to attach to the subscription and receive events that arrived while it was disconnected. If multiple apps connect to the same subscription, events are workload balanced across the connected application instances | `string` | | `transport` | The transport plugin responsible for event delivery (WebSockets, Webhooks, JMS, NATS etc.) | `string` | | `filter` | Server-side filter to apply to events | [`SubscriptionFilter`](#subscriptionfilter) | | `options` | Subscription options | [`SubscriptionOptions`](#subscriptionoptions) | | `ephemeral` | Ephemeral subscriptions only exist as long as the application is connected, and as such will miss events that occur while the application is disconnected, and cannot be created administratively. You can create one over over a connected WebSocket connection | `bool` | -| `created` | Creation time of the subscription | [`FFTime`](simpletypes#fftime) | -| `updated` | Last time the subscription was updated | [`FFTime`](simpletypes#fftime) | +| `created` | Creation time of the subscription | [`FFTime`](simpletypes.md#fftime) | +| `updated` | Last time the subscription was updated | [`FFTime`](simpletypes.md#fftime) | ## SubscriptionFilter diff --git a/docs/reference/types/tokenapproval.md b/doc-site/docs/reference/types/tokenapproval.md similarity index 85% rename from docs/reference/types/tokenapproval.md rename to doc-site/docs/reference/types/tokenapproval.md index 89a61236a..5079acddc 100644 --- a/docs/reference/types/tokenapproval.md +++ b/doc-site/docs/reference/types/tokenapproval.md @@ -1,24 +1,7 @@ --- -layout: default title: TokenApproval -parent: Core Resources -grand_parent: pages.reference -nav_order: 13 --- - -# TokenApproval -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## TokenApproval - -{% include_relative _includes/tokenapproval_description.md %} +{% include-markdown "./_includes/tokenapproval_description.md" %} ### Example @@ -51,29 +34,29 @@ nav_order: 13 | Field Name | Description | Type | |------------|-------------|------| -| `localId` | The UUID of this token approval, in the local FireFly node | [`UUID`](simpletypes#uuid) | -| `pool` | The UUID the token pool this approval applies to | [`UUID`](simpletypes#uuid) | +| `localId` | The UUID of this token approval, in the local FireFly node | [`UUID`](simpletypes.md#uuid) | +| `pool` | The UUID the token pool this approval applies to | [`UUID`](simpletypes.md#uuid) | | `connector` | The name of the token connector, as specified in the FireFly core configuration file. Required on input when there are more than one token connectors configured | `string` | | `key` | The blockchain signing key for the approval request. On input defaults to the first signing key of the organization that operates the node | `string` | | `operator` | The blockchain identity that is granted the approval | `string` | | `approved` | Whether this record grants permission for an operator to perform actions on the token balance (true), or revokes permission (false) | `bool` | -| `info` | Token connector specific information about the approval operation, such as whether it applied to a limited balance of a fungible token. See your chosen token connector documentation for details | [`JSONObject`](simpletypes#jsonobject) | +| `info` | Token connector specific information about the approval operation, such as whether it applied to a limited balance of a fungible token. See your chosen token connector documentation for details | [`JSONObject`](simpletypes.md#jsonobject) | | `namespace` | The namespace for the approval, which must match the namespace of the token pool | `string` | | `protocolId` | An alphanumerically sortable string that represents this event uniquely with respect to the blockchain | `string` | | `subject` | A string identifying the parties and entities in the scope of this approval, as provided by the token connector | `string` | | `active` | Indicates if this approval is currently active (only one approval can be active per subject) | `bool` | -| `message` | The UUID of a message that has been correlated with this approval using the data field of the approval in a compatible token connector | [`UUID`](simpletypes#uuid) | +| `message` | The UUID of a message that has been correlated with this approval using the data field of the approval in a compatible token connector | [`UUID`](simpletypes.md#uuid) | | `messageHash` | The hash of a message that has been correlated with this approval using the data field of the approval in a compatible token connector | `Bytes32` | -| `created` | The creation time of the token approval | [`FFTime`](simpletypes#fftime) | +| `created` | The creation time of the token approval | [`FFTime`](simpletypes.md#fftime) | | `tx` | If submitted via FireFly, this will reference the UUID of the FireFly transaction (if the token connector in use supports attaching data) | [`TransactionRef`](#transactionref) | -| `blockchainEvent` | The UUID of the blockchain event | [`UUID`](simpletypes#uuid) | -| `config` | Input only field, with token connector specific configuration of the approval. See your chosen token connector documentation for details | [`JSONObject`](simpletypes#jsonobject) | +| `blockchainEvent` | The UUID of the blockchain event | [`UUID`](simpletypes.md#uuid) | +| `config` | Input only field, with token connector specific configuration of the approval. See your chosen token connector documentation for details | [`JSONObject`](simpletypes.md#jsonobject) | ## TransactionRef | Field Name | Description | Type | |------------|-------------|------| | `type` | The type of the FireFly transaction | `FFEnum`: | -| `id` | The UUID of the FireFly transaction | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the FireFly transaction | [`UUID`](simpletypes.md#uuid) | diff --git a/docs/reference/types/tokenpool.md b/doc-site/docs/reference/types/tokenpool.md similarity index 87% rename from docs/reference/types/tokenpool.md rename to doc-site/docs/reference/types/tokenpool.md index 42099941d..eea664803 100644 --- a/docs/reference/types/tokenpool.md +++ b/doc-site/docs/reference/types/tokenpool.md @@ -1,24 +1,7 @@ --- -layout: default title: TokenPool -parent: Core Resources -grand_parent: pages.reference -nav_order: 11 --- - -# TokenPool -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## TokenPool - -{% include_relative _includes/tokenpool_description.md %} +{% include-markdown "./_includes/tokenpool_description.md" %} ### Example @@ -52,7 +35,7 @@ nav_order: 11 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the token pool | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the token pool | [`UUID`](simpletypes.md#uuid) | | `type` | The type of token the pool contains, such as fungible/non-fungible | `FFEnum`:
`"fungible"`
`"nonfungible"` | | `namespace` | The namespace for the token pool | `string` | | `name` | The name of the token pool. Note the name is not validated against the description of the token on the blockchain | `string` | @@ -63,15 +46,15 @@ nav_order: 11 | `symbol` | The token symbol. If supplied on input for an existing on-chain token, this must match the on-chain information | `string` | | `decimals` | Number of decimal places that this token has | `int` | | `connector` | The name of the token connector, as specified in the FireFly core configuration file that is responsible for the token pool. Required on input when multiple token connectors are configured | `string` | -| `message` | The UUID of the broadcast message used to inform the network about this pool | [`UUID`](simpletypes#uuid) | +| `message` | The UUID of the broadcast message used to inform the network about this pool | [`UUID`](simpletypes.md#uuid) | | `active` | Indicates whether the pool has been successfully activated with the token connector | `bool` | -| `created` | The creation time of the pool | [`FFTime`](simpletypes#fftime) | -| `config` | Input only field, with token connector specific configuration of the pool, such as an existing Ethereum address and block number to used to index the pool. See your chosen token connector documentation for details | [`JSONObject`](simpletypes#jsonobject) | -| `info` | Token connector specific information about the pool. See your chosen token connector documentation for details | [`JSONObject`](simpletypes#jsonobject) | +| `created` | The creation time of the pool | [`FFTime`](simpletypes.md#fftime) | +| `config` | Input only field, with token connector specific configuration of the pool, such as an existing Ethereum address and block number to used to index the pool. See your chosen token connector documentation for details | [`JSONObject`](simpletypes.md#jsonobject) | +| `info` | Token connector specific information about the pool. See your chosen token connector documentation for details | [`JSONObject`](simpletypes.md#jsonobject) | | `tx` | Reference to the FireFly transaction used to create and broadcast this pool to the network | [`TransactionRef`](#transactionref) | | `interface` | A reference to an existing FFI, containing pre-registered type information for the token contract | [`FFIReference`](#ffireference) | | `interfaceFormat` | The interface encoding format supported by the connector for this token pool | `FFEnum`:
`"abi"`
`"ffi"` | -| `methods` | The method definitions resolved by the token connector to be used by each token operation | [`JSONAny`](simpletypes#jsonany) | +| `methods` | The method definitions resolved by the token connector to be used by each token operation | [`JSONAny`](simpletypes.md#jsonany) | | `published` | Indicates if the token pool is published to other members of the multiparty network | `bool` | ## TransactionRef @@ -79,14 +62,14 @@ nav_order: 11 | Field Name | Description | Type | |------------|-------------|------| | `type` | The type of the FireFly transaction | `FFEnum`: | -| `id` | The UUID of the FireFly transaction | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the FireFly transaction | [`UUID`](simpletypes.md#uuid) | ## FFIReference | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the FireFly interface | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the FireFly interface | [`UUID`](simpletypes.md#uuid) | | `name` | The name of the FireFly interface | `string` | | `version` | The version of the FireFly interface | `string` | diff --git a/docs/reference/types/tokentransfer.md b/doc-site/docs/reference/types/tokentransfer.md similarity index 86% rename from docs/reference/types/tokentransfer.md rename to doc-site/docs/reference/types/tokentransfer.md index 59ea02240..f32f49e6b 100644 --- a/docs/reference/types/tokentransfer.md +++ b/doc-site/docs/reference/types/tokentransfer.md @@ -1,24 +1,7 @@ --- -layout: default title: TokenTransfer -parent: Core Resources -grand_parent: pages.reference -nav_order: 12 --- - -# TokenTransfer -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## TokenTransfer - -{% include_relative _includes/tokentransfer_description.md %} +{% include-markdown "./_includes/tokentransfer_description.md" %} ### Example @@ -50,8 +33,8 @@ nav_order: 12 | Field Name | Description | Type | |------------|-------------|------| | `type` | The type of transfer such as mint/burn/transfer | `FFEnum`:
`"mint"`
`"burn"`
`"transfer"` | -| `localId` | The UUID of this token transfer, in the local FireFly node | [`UUID`](simpletypes#uuid) | -| `pool` | The UUID the token pool this transfer applies to | [`UUID`](simpletypes#uuid) | +| `localId` | The UUID of this token transfer, in the local FireFly node | [`UUID`](simpletypes.md#uuid) | +| `pool` | The UUID the token pool this transfer applies to | [`UUID`](simpletypes.md#uuid) | | `tokenIndex` | The index of the token within the pool that this transfer applies to | `string` | | `uri` | The URI of the token this transfer applies to | `string` | | `connector` | The name of the token connector, as specified in the FireFly core configuration file. Required on input when there are more than one token connectors configured | `string` | @@ -59,20 +42,20 @@ nav_order: 12 | `key` | The blockchain signing key for the transfer. On input defaults to the first signing key of the organization that operates the node | `string` | | `from` | The source account for the transfer. On input defaults to the value of 'key' | `string` | | `to` | The target account for the transfer. On input defaults to the value of 'key' | `string` | -| `amount` | The amount for the transfer. For non-fungible tokens will always be 1. For fungible tokens, the number of decimals for the token pool should be considered when inputting the amount. For example, with 18 decimals a fractional balance of 10.234 will be specified as 10,234,000,000,000,000,000 | [`FFBigInt`](simpletypes#ffbigint) | +| `amount` | The amount for the transfer. For non-fungible tokens will always be 1. For fungible tokens, the number of decimals for the token pool should be considered when inputting the amount. For example, with 18 decimals a fractional balance of 10.234 will be specified as 10,234,000,000,000,000,000 | [`FFBigInt`](simpletypes.md#ffbigint) | | `protocolId` | An alphanumerically sortable string that represents this event uniquely with respect to the blockchain | `string` | -| `message` | The UUID of a message that has been correlated with this transfer using the data field of the transfer in a compatible token connector | [`UUID`](simpletypes#uuid) | +| `message` | The UUID of a message that has been correlated with this transfer using the data field of the transfer in a compatible token connector | [`UUID`](simpletypes.md#uuid) | | `messageHash` | The hash of a message that has been correlated with this transfer using the data field of the transfer in a compatible token connector | `Bytes32` | -| `created` | The creation time of the transfer | [`FFTime`](simpletypes#fftime) | +| `created` | The creation time of the transfer | [`FFTime`](simpletypes.md#fftime) | | `tx` | If submitted via FireFly, this will reference the UUID of the FireFly transaction (if the token connector in use supports attaching data) | [`TransactionRef`](#transactionref) | -| `blockchainEvent` | The UUID of the blockchain event | [`UUID`](simpletypes#uuid) | -| `config` | Input only field, with token connector specific configuration of the transfer. See your chosen token connector documentation for details | [`JSONObject`](simpletypes#jsonobject) | +| `blockchainEvent` | The UUID of the blockchain event | [`UUID`](simpletypes.md#uuid) | +| `config` | Input only field, with token connector specific configuration of the transfer. See your chosen token connector documentation for details | [`JSONObject`](simpletypes.md#jsonobject) | ## TransactionRef | Field Name | Description | Type | |------------|-------------|------| | `type` | The type of the FireFly transaction | `FFEnum`: | -| `id` | The UUID of the FireFly transaction | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the FireFly transaction | [`UUID`](simpletypes.md#uuid) | diff --git a/docs/reference/types/transaction.md b/doc-site/docs/reference/types/transaction.md similarity index 83% rename from docs/reference/types/transaction.md rename to doc-site/docs/reference/types/transaction.md index 7125d8245..4db97c3cb 100644 --- a/docs/reference/types/transaction.md +++ b/doc-site/docs/reference/types/transaction.md @@ -1,24 +1,7 @@ --- -layout: default title: Transaction -parent: Core Resources -grand_parent: pages.reference -nav_order: 6 --- - -# Transaction -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## Transaction - -{% include_relative _includes/transaction_description.md %} +{% include-markdown "./_includes/transaction_description.md" %} ### Example @@ -38,10 +21,10 @@ nav_order: 6 | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the FireFly transaction | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the FireFly transaction | [`UUID`](simpletypes.md#uuid) | | `namespace` | The namespace of the FireFly transaction | `string` | | `type` | The type of the FireFly transaction | `FFEnum`:
`"none"`
`"unpinned"`
`"batch_pin"`
`"network_action"`
`"token_pool"`
`"token_transfer"`
`"contract_deploy"`
`"contract_invoke"`
`"contract_invoke_pin"`
`"token_approval"`
`"data_publish"` | -| `created` | The time the transaction was created on this node. Note the transaction is individually created with the same UUID on each participant in the FireFly transaction | [`FFTime`](simpletypes#fftime) | +| `created` | The time the transaction was created on this node. Note the transaction is individually created with the same UUID on each participant in the FireFly transaction | [`FFTime`](simpletypes.md#fftime) | | `idempotencyKey` | An optional unique identifier for a transaction. Cannot be duplicated within a namespace, thus allowing idempotent submission of transactions to the API | `IdempotencyKey` | | `blockchainIds` | The blockchain transaction ID, in the format specific to the blockchain involved in the transaction. Not all FireFly transactions include a blockchain. FireFly transactions are extensible to support multiple blockchain transactions | `string[]` | diff --git a/docs/reference/types/verifier.md b/doc-site/docs/reference/types/verifier.md similarity index 75% rename from docs/reference/types/verifier.md rename to doc-site/docs/reference/types/verifier.md index caebcfdd0..09e7975b8 100644 --- a/docs/reference/types/verifier.md +++ b/doc-site/docs/reference/types/verifier.md @@ -1,24 +1,7 @@ --- -layout: default title: Verifier -parent: Core Resources -grand_parent: pages.reference -nav_order: 15 --- - -# Verifier -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## Verifier - -{% include_relative _includes/verifier_description.md %} +{% include-markdown "./_includes/verifier_description.md" %} ### Example @@ -37,9 +20,9 @@ nav_order: 15 | Field Name | Description | Type | |------------|-------------|------| | `hash` | Hash used as a globally consistent identifier for this namespace + type + value combination on every node in the network | `Bytes32` | -| `identity` | The UUID of the parent identity that has claimed this verifier | [`UUID`](simpletypes#uuid) | +| `identity` | The UUID of the parent identity that has claimed this verifier | [`UUID`](simpletypes.md#uuid) | | `namespace` | The namespace of the verifier | `string` | | `type` | The type of the verifier | `FFEnum`:
`"ethereum_address"`
`"tezos_address"`
`"fabric_msp_id"`
`"dx_peer_id"` | | `value` | The verifier string, such as an Ethereum address, or Fabric MSP identifier | `string` | -| `created` | The time this verifier was created on this node | [`FFTime`](simpletypes#fftime) | +| `created` | The time this verifier was created on this node | [`FFTime`](simpletypes.md#fftime) | diff --git a/docs/reference/types/wsack.md b/doc-site/docs/reference/types/wsack.md similarity index 75% rename from docs/reference/types/wsack.md rename to doc-site/docs/reference/types/wsack.md index fc44ff2f0..005302101 100644 --- a/docs/reference/types/wsack.md +++ b/doc-site/docs/reference/types/wsack.md @@ -1,24 +1,7 @@ --- -layout: default title: WSAck -parent: Core Resources -grand_parent: pages.reference -nav_order: 24 --- - -# WSAck -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## WSAck - -{% include_relative _includes/wsack_description.md %} +{% include-markdown "./_includes/wsack_description.md" %} ### Example @@ -38,14 +21,14 @@ nav_order: 24 | Field Name | Description | Type | |------------|-------------|------| | `type` | WSActionBase.type | `FFEnum`:
`"start"`
`"ack"`
`"protocol_error"`
`"event_batch"` | -| `id` | WSAck.id | [`UUID`](simpletypes#uuid) | +| `id` | WSAck.id | [`UUID`](simpletypes.md#uuid) | | `subscription` | WSAck.subscription | [`SubscriptionRef`](#subscriptionref) | ## SubscriptionRef | Field Name | Description | Type | |------------|-------------|------| -| `id` | The UUID of the subscription | [`UUID`](simpletypes#uuid) | +| `id` | The UUID of the subscription | [`UUID`](simpletypes.md#uuid) | | `namespace` | The namespace of the subscription. A subscription will only receive events generated in the namespace of the subscription | `string` | | `name` | The name of the subscription. The application specifies this name when it connects, in order to attach to the subscription and receive events that arrived while it was disconnected. If multiple apps connect to the same subscription, events are workload balanced across the connected application instances | `string` | diff --git a/docs/reference/types/wserror.md b/doc-site/docs/reference/types/wserror.md similarity index 62% rename from docs/reference/types/wserror.md rename to doc-site/docs/reference/types/wserror.md index ed2cb06e1..51813199a 100644 --- a/docs/reference/types/wserror.md +++ b/doc-site/docs/reference/types/wserror.md @@ -1,24 +1,7 @@ --- -layout: default title: WSError -parent: Core Resources -grand_parent: pages.reference -nav_order: 25 --- - -# WSError -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## WSError - -{% include_relative _includes/wserror_description.md %} +{% include-markdown "./_includes/wserror_description.md" %} ### Example diff --git a/docs/reference/types/wsstart.md b/doc-site/docs/reference/types/wsstart.md similarity index 97% rename from docs/reference/types/wsstart.md rename to doc-site/docs/reference/types/wsstart.md index 3b854027e..9c674338b 100644 --- a/docs/reference/types/wsstart.md +++ b/doc-site/docs/reference/types/wsstart.md @@ -1,24 +1,7 @@ --- -layout: default title: WSStart -parent: Core Resources -grand_parent: pages.reference -nav_order: 23 --- - -# WSStart -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## WSStart - -{% include_relative _includes/wsstart_description.md %} +{% include-markdown "./_includes/wsstart_description.md" %} ### Example diff --git a/docs/releasenotes/1.1_migration_guide.md b/doc-site/docs/releasenotes/1.1_migration_guide.md similarity index 98% rename from docs/releasenotes/1.1_migration_guide.md rename to doc-site/docs/releasenotes/1.1_migration_guide.md index 578c07486..896af8e20 100644 --- a/docs/releasenotes/1.1_migration_guide.md +++ b/doc-site/docs/releasenotes/1.1_migration_guide.md @@ -1,20 +1,8 @@ --- -layout: default title: v1.1.0 Migration Guide -parent: pages.release_notes -nav_order: 2 --- # v1.1.0 Migration Guide -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- ## Overview diff --git a/docs/releasenotes/1.2_migration_guide.md b/doc-site/docs/releasenotes/1.2_migration_guide.md similarity index 98% rename from docs/releasenotes/1.2_migration_guide.md rename to doc-site/docs/releasenotes/1.2_migration_guide.md index 11a116116..c5cce9a84 100644 --- a/docs/releasenotes/1.2_migration_guide.md +++ b/doc-site/docs/releasenotes/1.2_migration_guide.md @@ -1,20 +1,8 @@ --- -layout: default title: v1.2.0 Migration Guide -parent: pages.release_notes -nav_order: 1 --- # v1.2.0 Migration Guide -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- ## Overview @@ -248,4 +236,4 @@ In previous versions of FireFly, transaction output details used to appear under ## Local development considerations -It is also worth noting that the default Ethereum blockchain connector in the FireFly CLI is now Evmconnect. Ethconnect is still fully supported, but FireFly v1.2.0 marks a point of maturity in the project where it is now the recommended choice for any Ethereum based FireFly stack. \ No newline at end of file +It is also worth noting that the default Ethereum blockchain connector in the FireFly CLI is now Evmconnect. Ethconnect is still fully supported, but FireFly v1.2.0 marks a point of maturity in the project where it is now the recommended choice for any Ethereum based FireFly stack. diff --git a/docs/releasenotes/index.md b/doc-site/docs/releasenotes/index.md similarity index 98% rename from docs/releasenotes/index.md rename to doc-site/docs/releasenotes/index.md index 61b34f449..c88fa4018 100644 --- a/docs/releasenotes/index.md +++ b/doc-site/docs/releasenotes/index.md @@ -1,12 +1,7 @@ --- -layout: i18n_page -title: pages.release_notes -nav_order: 10 -has_children: true +title: Release Notes --- -# Release Notes - [Full release notes](https://github.com/hyperledger/firefly/releases) ## [v1.2.0 - February 6, 2023](https://github.com/hyperledger/firefly/releases/tag/v1.2.0) diff --git a/doc-site/docs/stylesheets/extra.css b/doc-site/docs/stylesheets/extra.css new file mode 100644 index 000000000..d56bec0e8 --- /dev/null +++ b/doc-site/docs/stylesheets/extra.css @@ -0,0 +1,3 @@ +:root { + --md-primary-fg-color: #472EE0; + } \ No newline at end of file diff --git a/docs/swagger/swagger.md b/doc-site/docs/swagger/index.md similarity index 92% rename from docs/swagger/swagger.md rename to doc-site/docs/swagger/index.md index 1df28d261..5f41c02f8 100644 --- a/docs/swagger/swagger.md +++ b/doc-site/docs/swagger/index.md @@ -1,12 +1,7 @@ --- -layout: i18n_page -title: pages.api_spec -nav_order: 8 -has_children: false +title: API Spec --- -# API Spec - This is the FireFly OpenAPI Specification document generated by FireFly **Note**: The 'Try it out' buttons will not work on this page because it's not running against a live version of FireFly. To actually try it out, we recommend using the [FireFly CLI](https://github.com/hyperledger/firefly-cli) to start an instance on your local machine (which will start the FireFly core on port 5000 by default) and then open the Swagger UI associated with your local node by opening a new tab and visiting [http://localhost:5000/api](http://localhost:5000/api) @@ -41,7 +36,7 @@ window.onload = function() { plugins: [ SwaggerUIBundle.plugins.DownloadUrl ], - layout: "BaseLayout" + }); window.ui = ui; diff --git a/docs/swagger/swagger.yaml b/doc-site/docs/swagger/swagger.yaml similarity index 100% rename from docs/swagger/swagger.yaml rename to doc-site/docs/swagger/swagger.yaml diff --git a/docs/swagger/test.yaml b/doc-site/docs/swagger/test.yaml similarity index 100% rename from docs/swagger/test.yaml rename to doc-site/docs/swagger/test.yaml diff --git a/docs/tutorials/basic_auth.md b/doc-site/docs/tutorials/basic_auth.md similarity index 95% rename from docs/tutorials/basic_auth.md rename to doc-site/docs/tutorials/basic_auth.md index e58071d20..f584bd22e 100644 --- a/docs/tutorials/basic_auth.md +++ b/doc-site/docs/tutorials/basic_auth.md @@ -1,19 +1,5 @@ --- -layout: i18n_page -title: pages.basic_auth -parent: pages.tutorials -nav_order: 10 ---- - -# {%t pages.basic_auth %} -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - +title: Basic Auth --- ## Quick reference @@ -32,7 +18,7 @@ FireFly has a basic auth plugin built in, which we will be configuring in this t ## Additional info -- Config Reference: [HTTP Auth](../reference/config.html#httpauth) +- Config Reference: [HTTP Auth](../reference/config.md#httpauth) - [Auth plugin interface](https://github.com/hyperledger/firefly-common/blob/main/pkg/auth/plugin.go) - [Basic auth plugin implementation](https://github.com/hyperledger/firefly-common/blob/main/pkg/auth/basic/basic_auth.go) @@ -107,11 +93,12 @@ Edit the file to look like this, replacing the path to your `test_users` file: version: "2.1" services: firefly_core_0: - volumes: - - PATH_TO_YOUR_TEST_USERS_FILE:/etc/firefly/test_users + volumes: + - PATH_TO_YOUR_TEST_USERS_FILE:/etc/firefly/test_users ``` ### Restart your FireFly Core container + To restart your FireFly stack and have Docker pick up the new volume, run: ``` @@ -121,7 +108,6 @@ ff start > **NOTE**: The FireFly basic auth plugin reads this file at startup and will not read it again during runtime. If you add any users or change passwords, restarting the node will be necessary to use an updated file. - ### Test basic auth After FireFly starts back up, you should be able to test that auth is working correctly by making an unauthenticated request to the API: @@ -185,4 +171,4 @@ Adding the username and password that we set earlier, should make the request su ``` curl -u "firefly:firefly" http://127.0.0.1:5101/spi/v1/namespaces [{"name":"default","networkName":"default","description":"Default predefined namespace","created":"2022-10-18T16:35:57.603205507Z"}] -``` \ No newline at end of file +``` diff --git a/docs/tutorials/broadcast_data.md b/doc-site/docs/tutorials/broadcast_data.md similarity index 93% rename from docs/tutorials/broadcast_data.md rename to doc-site/docs/tutorials/broadcast_data.md index 0d974db4e..5ea6d7aed 100644 --- a/docs/tutorials/broadcast_data.md +++ b/doc-site/docs/tutorials/broadcast_data.md @@ -1,19 +1,5 @@ --- -layout: i18n_page -title: pages.broadcast_data -parent: pages.tutorials -nav_order: 1 ---- - -# Broadcast data -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - +title: Broadcast data --- ## Quick reference @@ -33,7 +19,7 @@ nav_order: 1 ## Additional info -- Key Concepts: [Broadcast / shared data](../overview/multiparty/broadcast.html) +- Key Concepts: [Broadcast / shared data](../overview/multiparty/broadcast.md) - Swagger Reference: POST /api/v1/namespaces/{ns}/messages/broadcast ## Example 1: Inline string data @@ -108,6 +94,7 @@ It is very good practice to set a `tag` and `topic` in each of your messages: ] } ``` + ## Notes on why setting a topic is important The FireFly aggregator uses the `topic` (obfuscated on chain) to determine if a @@ -137,16 +124,16 @@ on the vast majority of your messages. Here we make two API calls. -1) Create the `data` object explicitly, using a multi-part form upload +1. Create the `data` object explicitly, using a multi-part form upload - - You can also just post JSON to this endpoint +- You can also just post JSON to this endpoint -2) Broadcast a message referring to that data +2. Broadcast a message referring to that data - - The Blob attachment gets published to shared storage - - This happens the first time a broadcast happens on a data attachment - - A pin goes to the blockchain - - The metadata goes into a batch with the message +- The Blob attachment gets published to shared storage + - This happens the first time a broadcast happens on a data attachment +- A pin goes to the blockchain +- The metadata goes into a batch with the message ### Multipart form post of a file @@ -211,6 +198,7 @@ Just include a reference to the `id` returned from the upload. ``` ## Broadcasting Messages using the Sandbox + All of the functionality discussed above can be done through the [FireFly Sandbox](../gettingstarted/sandbox.md). To get started, open up the Web UI and Sanbox UI for at least one of your members. The URLs for these were printed in your terminal when you started your FireFly stack. diff --git a/docs/tutorials/chains/arbitrum.md b/doc-site/docs/tutorials/chains/arbitrum.md similarity index 94% rename from docs/tutorials/chains/arbitrum.md rename to doc-site/docs/tutorials/chains/arbitrum.md index f501b7938..c23c4ca82 100644 --- a/docs/tutorials/chains/arbitrum.md +++ b/doc-site/docs/tutorials/chains/arbitrum.md @@ -1,20 +1,5 @@ --- -layout: i18n_page -title: pages.arbitrum -parent: pages.chains -grand_parent: pages.tutorials -nav_order: 4 ---- - -# {%t pages.arbitrum %} -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - +title: Arbitrum --- Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This guide will walk you through the steps to create a local FireFly development environment and connect it to the Arbitrum Nitro Goerli Rollup Testnet. @@ -23,7 +8,7 @@ Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to [Install the FireFly CLI](../../gettingstarted/firefly_cli.md). -[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .btn .btn-purple .mb-5} +[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .md-button .md-button--primary} ## Create an `evmconnect.yml` config file diff --git a/docs/tutorials/chains/avalanche.md b/doc-site/docs/tutorials/chains/avalanche.md similarity index 94% rename from docs/tutorials/chains/avalanche.md rename to doc-site/docs/tutorials/chains/avalanche.md index 0bdb03927..01f0f10cf 100644 --- a/docs/tutorials/chains/avalanche.md +++ b/doc-site/docs/tutorials/chains/avalanche.md @@ -1,20 +1,5 @@ --- -layout: i18n_page -title: pages.avalanche -parent: pages.chains -grand_parent: pages.tutorials -nav_order: 3 ---- - -# {%t pages.avalanche %} -{: .no_toc } - -## Table of contents - -{: .no_toc .text-delta } -1. TOC -{:toc} - +title: Aavalanche --- Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This guide will walk you through the steps to create a local FireFly development environment and connect it to the Avalanche C-Chain Fuji testnet. @@ -23,7 +8,7 @@ Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to [Install the FireFly CLI](../../gettingstarted/firefly_cli.md). -[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .btn .btn-purple .mb-5} +[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .md-button .md-button--primary} ## Create an `evmconnect.yml` config file diff --git a/docs/tutorials/chains/binance_smart_chain.md b/doc-site/docs/tutorials/chains/binance_smart_chain.md similarity index 94% rename from docs/tutorials/chains/binance_smart_chain.md rename to doc-site/docs/tutorials/chains/binance_smart_chain.md index c2091c849..81ef5f5dc 100644 --- a/docs/tutorials/chains/binance_smart_chain.md +++ b/doc-site/docs/tutorials/chains/binance_smart_chain.md @@ -1,20 +1,5 @@ --- -layout: i18n_page -title: pages.binance_smart_chain -parent: pages.chains -grand_parent: pages.tutorials -nav_order: 2 ---- - -# {%t pages.binance_smart_chain %} -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - +title: Binance Smart Chain --- Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This guide will walk you through the steps to create a local FireFly development environment and connect it to the public Binance Smart Chain testnet. @@ -23,7 +8,7 @@ Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to [Install the FireFly CLI](../../gettingstarted/firefly_cli.md). -[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .btn .btn-purple .mb-5} +[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .md-button .md-button--primary} ## Create an `evmconnect.yml` config file diff --git a/docs/tutorials/chains/fabric_test_network.md b/doc-site/docs/tutorials/chains/fabric_test_network.md similarity index 70% rename from docs/tutorials/chains/fabric_test_network.md rename to doc-site/docs/tutorials/chains/fabric_test_network.md index 1f37d883b..e6a84eaf3 100644 --- a/docs/tutorials/chains/fabric_test_network.md +++ b/doc-site/docs/tutorials/chains/fabric_test_network.md @@ -1,28 +1,16 @@ --- -layout: i18n_page -title: pages.fabric_test_network -parent: pages.chains -grand_parent: pages.tutorials -nav_order: 7 +title: Fabric Test Network --- # Work with Fabric-Samples Test Network -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- This guide will walk you through the steps to create a local FireFly development environment and connect it to the Fabric Test Network from the [Fabric Samples repo](https://github.com/hyperledger/fabric-samples) ## Previous steps: Install the FireFly CLI + If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to [Install the FireFly CLI](../../gettingstarted/firefly_cli.md). -[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .btn .btn-purple .mb-5} +[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .md-button .md-button--primary} ## Start Fabric Test Network with Fabric CA @@ -36,7 +24,7 @@ For details about the Fabric Test Network and how to set it up, please see the [ ## Deploy FireFly Chaincode -Next we will need to package and deploy the FireFly chaincode to `mychannel` in our new network. For more details on packaging and deploying chaincode, please see the [Fabric chaincode lifecycle documentation](https://hyperledger-fabric.readthedocs.io/en/latest/chaincode_lifecycle.html). If you already have the [FireFly repo](https://github.com/hyperledger/firefly) cloned in the same directory as your `fabric-samples` repo, you can run the following script from your `test-network` directory: +Next we will need to package and deploy the FireFly chaincode to `mychannel` in our new network. For more details on packaging and deploying chaincode, please see the [Fabric chaincode lifecycle documentation](https://hyperledger-fabric.readthedocs.io/en/latest/chaincode_lifecycle.md). If you already have the [FireFly repo](https://github.com/hyperledger/firefly) cloned in the same directory as your `fabric-samples` repo, you can run the following script from your `test-network` directory: > **NOTE**: This script is provided as a convenience only, and you are not required to use it. You are welcome to package and deploy the chaincode to your test-network any way you would like. @@ -87,7 +75,7 @@ peer lifecycle chaincode commit -o localhost:7050 --ordererTLSHostnameOverride o ## Create `ccp.yml` documents -Each FireFly Supernode (specifically the Fabconnect instance in each) will need to know how to connect to the Fabric network. Fabconnect will use a [Fabric Connection Profile](https://hyperledger-fabric.readthedocs.io/en/release-2.2/developapps/connectionprofile.html) which describes the network and tells it where the certs and keys are that it needs. Below is a `ccp.yml` for each organization. You will need to fill in one line by replacing the string `FILL_IN_KEY_NAME_HERE`, because the file name of the private key for each user is randomly generated. +Each FireFly Supernode (specifically the Fabconnect instance in each) will need to know how to connect to the Fabric network. Fabconnect will use a [Fabric Connection Profile](https://hyperledger-fabric.readthedocs.io/en/release-2.2/developapps/connectionprofile.md) which describes the network and tells it where the certs and keys are that it needs. Below is a `ccp.yml` for each organization. You will need to fill in one line by replacing the string `FILL_IN_KEY_NAME_HERE`, because the file name of the private key for each user is randomly generated. ### Organization 1 connection profile @@ -95,67 +83,67 @@ Create a new file at `~/org1_ccp.yml` with the contents below. Replace the strin ```yml certificateAuthorities: - org1.example.com: - tlsCACerts: - path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp/tlscacerts/ca.crt - url: https://ca_org1:7054 - grpcOptions: - ssl-target-name-override: org1.example.com - registrar: - enrollId: admin - enrollSecret: adminpw + org1.example.com: + tlsCACerts: + path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp/tlscacerts/ca.crt + url: https://ca_org1:7054 + grpcOptions: + ssl-target-name-override: org1.example.com + registrar: + enrollId: admin + enrollSecret: adminpw channels: - mychannel: - orderers: - - fabric_orderer - peers: - fabric_peer: - chaincodeQuery: true - endorsingPeer: true - eventSource: true - ledgerQuery: true + mychannel: + orderers: + - fabric_orderer + peers: + fabric_peer: + chaincodeQuery: true + endorsingPeer: true + eventSource: true + ledgerQuery: true client: - BCCSP: - security: - default: - provider: SW - enabled: true - hashAlgorithm: SHA2 - level: 256 - softVerify: true - credentialStore: - cryptoStore: - path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp - path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp - cryptoconfig: - path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp - logging: - level: info - organization: org1.example.com - tlsCerts: - client: - cert: - path: /etc/firefly/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/signcerts/cert.pem - key: - path: /etc/firefly/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore/FILL_IN_KEY_NAME_HERE + BCCSP: + security: + default: + provider: SW + enabled: true + hashAlgorithm: SHA2 + level: 256 + softVerify: true + credentialStore: + cryptoStore: + path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp + path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp + cryptoconfig: + path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp + logging: + level: info + organization: org1.example.com + tlsCerts: + client: + cert: + path: /etc/firefly/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/signcerts/cert.pem + key: + path: /etc/firefly/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore/FILL_IN_KEY_NAME_HERE orderers: - fabric_orderer: - tlsCACerts: - path: /etc/firefly/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/tls/tlscacerts/tls-localhost-9054-ca-orderer.pem - url: grpcs://orderer.example.com:7050 + fabric_orderer: + tlsCACerts: + path: /etc/firefly/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/tls/tlscacerts/tls-localhost-9054-ca-orderer.pem + url: grpcs://orderer.example.com:7050 organizations: - org1.example.com: - certificateAuthorities: - - org1.example.com - cryptoPath: /tmp/msp - mspid: Org1MSP - peers: - - fabric_peer + org1.example.com: + certificateAuthorities: + - org1.example.com + cryptoPath: /tmp/msp + mspid: Org1MSP + peers: + - fabric_peer peers: - fabric_peer: - tlsCACerts: - path: /etc/firefly/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/tlscacerts/tls-localhost-7054-ca-org1.pem - url: grpcs://peer0.org1.example.com:7051 + fabric_peer: + tlsCACerts: + path: /etc/firefly/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/tlscacerts/tls-localhost-7054-ca-org1.pem + url: grpcs://peer0.org1.example.com:7051 version: 1.1.0% ``` @@ -165,67 +153,67 @@ Create a new file at `~/org2_ccp.yml` with the contents below. Replace the strin ```yml certificateAuthorities: - org2.example.com: - tlsCACerts: - path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp/tlscacerts/ca.crt - url: https://ca_org2:8054 - grpcOptions: - ssl-target-name-override: org2.example.com - registrar: - enrollId: admin - enrollSecret: adminpw + org2.example.com: + tlsCACerts: + path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp/tlscacerts/ca.crt + url: https://ca_org2:8054 + grpcOptions: + ssl-target-name-override: org2.example.com + registrar: + enrollId: admin + enrollSecret: adminpw channels: - mychannel: - orderers: - - fabric_orderer - peers: - fabric_peer: - chaincodeQuery: true - endorsingPeer: true - eventSource: true - ledgerQuery: true + mychannel: + orderers: + - fabric_orderer + peers: + fabric_peer: + chaincodeQuery: true + endorsingPeer: true + eventSource: true + ledgerQuery: true client: - BCCSP: - security: - default: - provider: SW - enabled: true - hashAlgorithm: SHA2 - level: 256 - softVerify: true - credentialStore: - cryptoStore: - path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp - path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp - cryptoconfig: - path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp - logging: - level: info - organization: org2.example.com - tlsCerts: - client: - cert: - path: /etc/firefly/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp/signcerts/cert.pem - key: - path: /etc/firefly/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp/keystore/FILL_IN_KEY_NAME_HERE + BCCSP: + security: + default: + provider: SW + enabled: true + hashAlgorithm: SHA2 + level: 256 + softVerify: true + credentialStore: + cryptoStore: + path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp + path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp + cryptoconfig: + path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp + logging: + level: info + organization: org2.example.com + tlsCerts: + client: + cert: + path: /etc/firefly/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp/signcerts/cert.pem + key: + path: /etc/firefly/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp/keystore/FILL_IN_KEY_NAME_HERE orderers: - fabric_orderer: - tlsCACerts: - path: /etc/firefly/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/tls/tlscacerts/tls-localhost-9054-ca-orderer.pem - url: grpcs://orderer.example.com:7050 + fabric_orderer: + tlsCACerts: + path: /etc/firefly/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/tls/tlscacerts/tls-localhost-9054-ca-orderer.pem + url: grpcs://orderer.example.com:7050 organizations: - org2.example.com: - certificateAuthorities: - - org2.example.com - cryptoPath: /tmp/msp - mspid: Org2MSP - peers: - - fabric_peer + org2.example.com: + certificateAuthorities: + - org2.example.com + cryptoPath: /tmp/msp + mspid: Org2MSP + peers: + - fabric_peer peers: - fabric_peer: - tlsCACerts: - path: /etc/firefly/organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/tlscacerts/tls-localhost-8054-ca-org2.pem - url: grpcs://peer0.org2.example.com:9051 + fabric_peer: + tlsCACerts: + path: /etc/firefly/organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/tlscacerts/tls-localhost-8054-ca-org2.pem + url: grpcs://peer0.org2.example.com:9051 version: 1.1.0% ``` @@ -278,7 +266,6 @@ This same guide can be adapted to connect to a remote Fabric network running som - You need to provide a connection profile and the correct certs, keys, etc. for each node when you run `ff init` - Your FireFly containers will need to have network access to your Fabric network - ## Troubleshooting There are quite a few moving parts in this guide and if steps are missed or done out of order it can cause problems. Below are some of the common situations that you might run into while following this guide, and solutions for each. @@ -315,4 +302,4 @@ If you see something in your logs that looks like the above, there could be a co User credentials store creation failed. Failed to load identity configurations: failed to create identity config from backends: failed to load client TLSConfig : failed to load client key: failed to load pem bytes from path /etc/firefly/organizations/peerOrganizations/org1.example.com/users/User1@org1.example.com/msp/keystore/cfc50311e2204f232cfdfaf4eba7731279f2366ec291ca1c1781e2bf7bc75529_sk: open /etc/firefly/organizations/peerOrganizations/org1.example.com/users/User1@org1.example.com/msp/keystore/cfc50311e2204f232cfdfaf4eba7731279f2366ec291ca1c1781e2bf7bc75529_sk: no such file or directory ``` -If you see something in your logs that looks like the above, it's likely that your private key file name is not correct in your `ccp.yml` file for that particular member. Check your `ccp.yml` and make sure all the files listed there exist in your `organizations` directory. \ No newline at end of file +If you see something in your logs that looks like the above, it's likely that your private key file name is not correct in your `ccp.yml` file for that particular member. Check your `ccp.yml` and make sure all the files listed there exist in your `organizations` directory. diff --git a/docs/tutorials/chains/images/arbitrum_faucet.png b/doc-site/docs/tutorials/chains/images/arbitrum_faucet.png similarity index 100% rename from docs/tutorials/chains/images/arbitrum_faucet.png rename to doc-site/docs/tutorials/chains/images/arbitrum_faucet.png diff --git a/docs/tutorials/chains/images/arbitrum_scan.png b/doc-site/docs/tutorials/chains/images/arbitrum_scan.png similarity index 100% rename from docs/tutorials/chains/images/arbitrum_scan.png rename to doc-site/docs/tutorials/chains/images/arbitrum_scan.png diff --git a/docs/tutorials/chains/images/avalanche_faucet.png b/doc-site/docs/tutorials/chains/images/avalanche_faucet.png similarity index 100% rename from docs/tutorials/chains/images/avalanche_faucet.png rename to doc-site/docs/tutorials/chains/images/avalanche_faucet.png diff --git a/docs/tutorials/chains/images/avalanche_snowtrace_scan.png b/doc-site/docs/tutorials/chains/images/avalanche_snowtrace_scan.png similarity index 100% rename from docs/tutorials/chains/images/avalanche_snowtrace_scan.png rename to doc-site/docs/tutorials/chains/images/avalanche_snowtrace_scan.png diff --git a/docs/tutorials/chains/images/bsc_faucet.png b/doc-site/docs/tutorials/chains/images/bsc_faucet.png similarity index 100% rename from docs/tutorials/chains/images/bsc_faucet.png rename to doc-site/docs/tutorials/chains/images/bsc_faucet.png diff --git a/docs/tutorials/chains/images/bsc_scan.png b/doc-site/docs/tutorials/chains/images/bsc_scan.png similarity index 100% rename from docs/tutorials/chains/images/bsc_scan.png rename to doc-site/docs/tutorials/chains/images/bsc_scan.png diff --git a/docs/tutorials/chains/images/moonbase_faucet.png b/doc-site/docs/tutorials/chains/images/moonbase_faucet.png similarity index 100% rename from docs/tutorials/chains/images/moonbase_faucet.png rename to doc-site/docs/tutorials/chains/images/moonbase_faucet.png diff --git a/docs/tutorials/chains/images/moonscan.png b/doc-site/docs/tutorials/chains/images/moonscan.png similarity index 100% rename from docs/tutorials/chains/images/moonscan.png rename to doc-site/docs/tutorials/chains/images/moonscan.png diff --git a/docs/tutorials/chains/images/near_account.png b/doc-site/docs/tutorials/chains/images/near_account.png similarity index 100% rename from docs/tutorials/chains/images/near_account.png rename to doc-site/docs/tutorials/chains/images/near_account.png diff --git a/docs/tutorials/chains/images/near_account_lookup.png b/doc-site/docs/tutorials/chains/images/near_account_lookup.png similarity index 100% rename from docs/tutorials/chains/images/near_account_lookup.png rename to doc-site/docs/tutorials/chains/images/near_account_lookup.png diff --git a/docs/tutorials/chains/images/near_account_name.png b/doc-site/docs/tutorials/chains/images/near_account_name.png similarity index 100% rename from docs/tutorials/chains/images/near_account_name.png rename to doc-site/docs/tutorials/chains/images/near_account_name.png diff --git a/docs/tutorials/chains/images/near_faucet.png b/doc-site/docs/tutorials/chains/images/near_faucet.png similarity index 100% rename from docs/tutorials/chains/images/near_faucet.png rename to doc-site/docs/tutorials/chains/images/near_faucet.png diff --git a/docs/tutorials/chains/images/near_fund_account.png b/doc-site/docs/tutorials/chains/images/near_fund_account.png similarity index 100% rename from docs/tutorials/chains/images/near_fund_account.png rename to doc-site/docs/tutorials/chains/images/near_fund_account.png diff --git a/docs/tutorials/chains/images/near_navigate_to_wallet.png b/doc-site/docs/tutorials/chains/images/near_navigate_to_wallet.png similarity index 100% rename from docs/tutorials/chains/images/near_navigate_to_wallet.png rename to doc-site/docs/tutorials/chains/images/near_navigate_to_wallet.png diff --git a/docs/tutorials/chains/images/near_scan.png b/doc-site/docs/tutorials/chains/images/near_scan.png similarity index 100% rename from docs/tutorials/chains/images/near_scan.png rename to doc-site/docs/tutorials/chains/images/near_scan.png diff --git a/docs/tutorials/chains/images/near_wallet_send_funds.png b/doc-site/docs/tutorials/chains/images/near_wallet_send_funds.png similarity index 100% rename from docs/tutorials/chains/images/near_wallet_send_funds.png rename to doc-site/docs/tutorials/chains/images/near_wallet_send_funds.png diff --git a/docs/tutorials/chains/images/optimism_faucet.png b/doc-site/docs/tutorials/chains/images/optimism_faucet.png similarity index 100% rename from docs/tutorials/chains/images/optimism_faucet.png rename to doc-site/docs/tutorials/chains/images/optimism_faucet.png diff --git a/docs/tutorials/chains/images/optimism_scan.png b/doc-site/docs/tutorials/chains/images/optimism_scan.png similarity index 100% rename from docs/tutorials/chains/images/optimism_scan.png rename to doc-site/docs/tutorials/chains/images/optimism_scan.png diff --git a/docs/tutorials/chains/images/polygon_faucet.png b/doc-site/docs/tutorials/chains/images/polygon_faucet.png similarity index 100% rename from docs/tutorials/chains/images/polygon_faucet.png rename to doc-site/docs/tutorials/chains/images/polygon_faucet.png diff --git a/docs/tutorials/chains/images/polygonscan_matic.png b/doc-site/docs/tutorials/chains/images/polygonscan_matic.png similarity index 100% rename from docs/tutorials/chains/images/polygonscan_matic.png rename to doc-site/docs/tutorials/chains/images/polygonscan_matic.png diff --git a/docs/tutorials/chains/images/tezos_explorer.png b/doc-site/docs/tutorials/chains/images/tezos_explorer.png similarity index 100% rename from docs/tutorials/chains/images/tezos_explorer.png rename to doc-site/docs/tutorials/chains/images/tezos_explorer.png diff --git a/docs/tutorials/chains/images/tezos_faucet.png b/doc-site/docs/tutorials/chains/images/tezos_faucet.png similarity index 100% rename from docs/tutorials/chains/images/tezos_faucet.png rename to doc-site/docs/tutorials/chains/images/tezos_faucet.png diff --git a/docs/tutorials/chains/images/xdc_explorer.png b/doc-site/docs/tutorials/chains/images/xdc_explorer.png similarity index 100% rename from docs/tutorials/chains/images/xdc_explorer.png rename to doc-site/docs/tutorials/chains/images/xdc_explorer.png diff --git a/docs/tutorials/chains/images/xdc_faucet.png b/doc-site/docs/tutorials/chains/images/xdc_faucet.png similarity index 100% rename from docs/tutorials/chains/images/xdc_faucet.png rename to doc-site/docs/tutorials/chains/images/xdc_faucet.png diff --git a/docs/tutorials/chains/images/zksync_explorer.png b/doc-site/docs/tutorials/chains/images/zksync_explorer.png similarity index 100% rename from docs/tutorials/chains/images/zksync_explorer.png rename to doc-site/docs/tutorials/chains/images/zksync_explorer.png diff --git a/docs/tutorials/chains/images/zksync_faucet.png b/doc-site/docs/tutorials/chains/images/zksync_faucet.png similarity index 100% rename from docs/tutorials/chains/images/zksync_faucet.png rename to doc-site/docs/tutorials/chains/images/zksync_faucet.png diff --git a/doc-site/docs/tutorials/chains/index.md b/doc-site/docs/tutorials/chains/index.md new file mode 100644 index 000000000..792e6a71e --- /dev/null +++ b/doc-site/docs/tutorials/chains/index.md @@ -0,0 +1,5 @@ +--- +title: Connecting to other blockchains +--- + +Write interesting stuff here diff --git a/docs/tutorials/chains/moonbeam.md b/doc-site/docs/tutorials/chains/moonbeam.md similarity index 94% rename from docs/tutorials/chains/moonbeam.md rename to doc-site/docs/tutorials/chains/moonbeam.md index 114b42091..e685eeb7b 100644 --- a/docs/tutorials/chains/moonbeam.md +++ b/doc-site/docs/tutorials/chains/moonbeam.md @@ -1,20 +1,5 @@ --- -layout: i18n_page -title: pages.moonbeam_testnet -parent: pages.chains -grand_parent: pages.tutorials -nav_order: 8 ---- - -# {%t pages.moonbeam_testnet %} -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - +title: Moonbeam Testnet --- Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This guide will walk you through the steps to create a local FireFly development environment and connect it to the public Moonbeam Alpha testnet. @@ -23,7 +8,7 @@ Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to [Install the FireFly CLI](../../gettingstarted/firefly_cli.md). -[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .btn .btn-purple .mb-5} +[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .md-button .md-button--primary} ## Create an `evmconnect.yml` config file diff --git a/docs/tutorials/chains/optimism.md b/doc-site/docs/tutorials/chains/optimism.md similarity index 75% rename from docs/tutorials/chains/optimism.md rename to doc-site/docs/tutorials/chains/optimism.md index 760fc1544..b7e438409 100644 --- a/docs/tutorials/chains/optimism.md +++ b/doc-site/docs/tutorials/chains/optimism.md @@ -1,54 +1,43 @@ --- -layout: i18n_page -title: pages.optimism -parent: pages.chains -grand_parent: pages.tutorials -nav_order: 5 ---- - - -# {%t pages.optimism %} -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - +title: Optimism --- Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This guide will walk you through the steps to create a local FireFly development environment and connect it to the Optimism Goerli testnet. ## Previous steps: Install the FireFly CLI + If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to [Install the FireFly CLI](../../gettingstarted/firefly_cli.md). -[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .btn .btn-purple .mb-5} +[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .md-button .md-button--primary} ## Create an `evmconnect.yml` config file + In order to connect to the Optimism testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called `evmconnect.yml` with the following contents: ```yml confirmations: - required: 4 # choose the number of confirmations you require + required: 4 # choose the number of confirmations you require policyengine.simple: - fixedGasPrice: null - gasOracle: - mode: connector + fixedGasPrice: null + gasOracle: + mode: connector ``` + For this tutorial, we will assume this file is saved at `~/Desktop/evmconnect.yml`. If your path is different, you will need to adjust the path in the next command below. ## Creating a new stack + To create a local FireFly development stack and connect it to the Optimism testnet, we will use command line flags to customize the following settings: - - Create a new Ethereum based stack named `optimism` with `1` member - - Disable `multiparty` mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here - - Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine. - - See the optimism [docs](https://community.optimism.io/docs/useful-tools/networks/) and select an HTTPS RPC endpoint. - - Set the chain ID to `420` (the correct ID for the Optimism testnet) - - Merge the custom config created above with the generated `evmconnect` config file +- Create a new Ethereum based stack named `optimism` with `1` member +- Disable `multiparty` mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here +- Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine. +- See the optimism [docs](https://community.optimism.io/docs/useful-tools/networks/) and select an HTTPS RPC endpoint. +- Set the chain ID to `420` (the correct ID for the Optimism testnet) +- Merge the custom config created above with the generated `evmconnect` config file To do this, run the following command: + ``` ff init ethereum optimism 1 \ --multiparty=false \ @@ -59,6 +48,7 @@ ff init ethereum optimism 1 \ ``` ## Start the stack + Now you should be able to start your stack by running: ``` @@ -78,6 +68,7 @@ ff logs optimism ``` ## Get some Optimism + At this point you should have a working FireFly stack, talking to a public chain. However, you won't be able to run any transactions just yet, because you don't have any way to pay for gas. A testnet faucet can give us some OP, the native token for Optimism. First, you will need to know what signing address your FireFly node is using. To check that, you can run: @@ -92,15 +83,16 @@ ff accounts list optimism ] ``` -Copy the address listed in the output from this command. Go to [https://optimismfaucet.xyz/](https://optimismfaucet.xyz/). You will need to login to your Github account and paste the address in the form. +Copy the address listed in the output from this command. Go to [https://optimismfaucet.xyz/](https://optimismfaucet.xyz/). You will need to login to your Github account and paste the address in the form. ![Optimism Faucet](images/optimism_faucet.png) ### Confirm the transaction on Blockcscout -You should be able to go lookup your account on [Blockscout for Optimism testnet https://blockscout.com/optimism/goerli](https://blockscout.com/optimism/goerli) and see that you now have a balance of 100 OP. Simply paste in your account address to search for it. +You should be able to go lookup your account on [Blockscout for Optimism testnet https://blockscout.com/optimism/goerli](https://blockscout.com/optimism/goerli) and see that you now have a balance of 100 OP. Simply paste in your account address to search for it. ![Blockscout Scan](images/optimism_scan.png) ## Use the public testnet -Now that you have everything set up, you can follow one of the other FireFly guides such as [Using Tokens](../tokens/index.md) or [Custom Smart Contracts](../custom_contracts/ethereum.md). For detailed instructions on deploying a custom smart contract to Optimism, please see the [Optimism docs](https://community.optimism.io/docs/developers/build/system-contracts/#getting-contract-artifacts-interfaces-and-abis) for instructions using various tools. \ No newline at end of file + +Now that you have everything set up, you can follow one of the other FireFly guides such as [Using Tokens](../tokens/index.md) or [Custom Smart Contracts](../custom_contracts/ethereum.md). For detailed instructions on deploying a custom smart contract to Optimism, please see the [Optimism docs](https://community.optimism.io/docs/developers/build/system-contracts/#getting-contract-artifacts-interfaces-and-abis) for instructions using various tools. diff --git a/docs/tutorials/chains/polygon_testnet.md b/doc-site/docs/tutorials/chains/polygon_testnet.md similarity index 94% rename from docs/tutorials/chains/polygon_testnet.md rename to doc-site/docs/tutorials/chains/polygon_testnet.md index c72836567..e86ba37eb 100644 --- a/docs/tutorials/chains/polygon_testnet.md +++ b/doc-site/docs/tutorials/chains/polygon_testnet.md @@ -1,20 +1,5 @@ --- -layout: i18n_page -title: pages.polygon_testnet -parent: pages.chains -grand_parent: pages.tutorials -nav_order: 1 ---- - -# {%t pages.polygon_testnet %} -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - +title: Polygon Testnet --- Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This guide will walk you through the steps to create a local FireFly development environment and connect it to the public Polygon Mumbai testnet. @@ -23,7 +8,7 @@ Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to [Install the FireFly CLI](../../gettingstarted/firefly_cli.md). -[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .btn .btn-purple .mb-5} +[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .md-button .md-button--primary} ## Create an `evmconnect.yml` config file @@ -105,6 +90,7 @@ Copy the address listed in the output from this command. Go to [https://faucet.p ![Polygon Faucet](images/polygon_faucet.png) ### Confirm the transaction on Polygonscan + You should be able to go lookup your account on [Polygonscan for the Mumbai testnet](https://mumbai.polygonscan.com/) and see that you now have a balance of 0.2 MATIC. Simply paste in your account address to search for it. You can also click on the **Internal Txns** tab from you account page to see the actual transfer of the MATIC from the faucet. diff --git a/docs/tutorials/chains/tezos_testnet.md b/doc-site/docs/tutorials/chains/tezos_testnet.md similarity index 91% rename from docs/tutorials/chains/tezos_testnet.md rename to doc-site/docs/tutorials/chains/tezos_testnet.md index 02ae39f9c..19707b92d 100644 --- a/docs/tutorials/chains/tezos_testnet.md +++ b/doc-site/docs/tutorials/chains/tezos_testnet.md @@ -1,17 +1,5 @@ --- -layout: i18n_page -title: pages.tezos_testnet -parent: pages.chains -grand_parent: pages.tutorials -nav_order: 6 ---- - -# {%t pages.tezos_testnet %} -{: .no_toc } - -1. TOC -{:toc} - +title: Tezos Testnet --- This guide will walk you through the steps to create a local FireFly development environment and connect it to the public Tezos Ghostnet testnet. @@ -20,15 +8,16 @@ This guide will walk you through the steps to create a local FireFly development If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to [Install the FireFly CLI](../../gettingstarted/firefly_cli.md). -[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .btn .btn-purple .mb-5} +[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .md-button .md-button--primary} ## Set up the transaction signing service [Signatory](https://signatory.io/) service allows to work with many different key-management systems.\ By default, FF uses [local signing](https://signatory.io/docs/file_based) option.\ However, it is also possible to configure the transaction signing service using key management systems such as: AWS/Google/Azure KMS, HCP Vault, etc. + > **NOTE**: The default option is not secure and is mainly used for development and demo purposes. Therefore, for the production, use the selected KMS.\ -The full list can be found [here](https://github.com/ecadlabs/signatory#backend-kmshsm-support-status). +> The full list can be found [here](https://github.com/ecadlabs/signatory#backend-kmshsm-support-status). ## Creating a new stack @@ -74,6 +63,7 @@ At this point you should have a working FireFly stack, talking to a public chain First, you need to get an account address, which was created during [signer set up](#signatory) step.\ To check that, you can run: + ``` ff accounts list dev [ @@ -84,12 +74,12 @@ ff accounts list dev ] ``` - After that, go to [Tezos Ghostnet Faucet](https://faucet.ghostnet.teztnets.xyz/) and paste the address in the form and click the **Request** button. ![Tezos Faucet](images/tezos_faucet.png) ### Confirm the transaction on TzStats + You should be able to go lookup your account on [TzStats for the Ghostnet testnet](https://ghost.tzstats.com/) and see that you now have a balance of 100 XTZ (or 2001 XTZ accordingly). Simply paste in your account address to search for it. On the **Transfers** tab from you account page you will see the actual transfer of the XTZ from the faucet. @@ -98,4 +88,4 @@ On the **Transfers** tab from you account page you will see the actual transfer ## Use the public testnet -Now that you have everything set up, you can follow one of the other FireFly guides such as [Custom Smart Contracts](../custom_contracts/tezos.md). For detailed instructions on deploying a custom smart contract to Tezos, please see the [Tezos docs](https://docs.tezos.com/smart-contracts/deploying) for instructions using various tools. \ No newline at end of file +Now that you have everything set up, you can follow one of the other FireFly guides such as [Custom Smart Contracts](../custom_contracts/tezos.md). For detailed instructions on deploying a custom smart contract to Tezos, please see the [Tezos docs](https://docs.tezos.com/smart-contracts/deploying) for instructions using various tools. diff --git a/docs/tutorials/chains/zksync_testnet.md b/doc-site/docs/tutorials/chains/zksync_testnet.md similarity index 73% rename from docs/tutorials/chains/zksync_testnet.md rename to doc-site/docs/tutorials/chains/zksync_testnet.md index c20241273..fbd6a61fa 100644 --- a/docs/tutorials/chains/zksync_testnet.md +++ b/doc-site/docs/tutorials/chains/zksync_testnet.md @@ -1,56 +1,45 @@ --- -layout: i18n_page -title: pages.zksync_testnet -parent: pages.chains -grand_parent: pages.tutorials -nav_order: 11 ---- - - -# {%t pages.zksync_testnet %} -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - +title: zkSync Testnet --- Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This guide will walk you through the steps to create a local FireFly development environment and connect it to the zkSync testnet. ## Previous steps: Install the FireFly CLI + If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to [Install the FireFly CLI](../../gettingstarted/firefly_cli.md). -[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .btn .btn-purple .mb-5} +[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .md-button .md-button--primary} ## Create an `evmconnect.yml` config file + In order to connect to the zkSync testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called `evmconnect.yml` with the following contents: ```yml confirmations: - required: 4 # choose the number of confirmations you require + required: 4 # choose the number of confirmations you require policyengine.simple: - fixedGasPrice: null - gasOracle: - mode: connector + fixedGasPrice: null + gasOracle: + mode: connector ``` + For this tutorial, we will assume this file is saved at `~/Desktop/evmconnect.yml`. If your path is different, you will need to adjust the path in the next command below. ## Creating a new stack + To create a local FireFly development stack and connect it to the zkSync testnet, we will use command line flags to customize the following settings: - - Create a new stack named `zkSync` with `1` member - - Disable `multiparty` mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here - - Connect to an ethereum network - - Use the `evmconnect` blockchain connector - - Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine. - - See the list of providers for zkSync [docs](https://v2-docs.zksync.io/dev/fundamentals/testnet.html). For this tutorial we will use `https://zksync2-testnet.zksync.dev` - - Set the chain ID to `280` (the correct ID for the zkSync testnet) - - Merge the custom config created above with the generated `evmconnect` config file +- Create a new stack named `zkSync` with `1` member +- Disable `multiparty` mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here +- Connect to an ethereum network +- Use the `evmconnect` blockchain connector +- Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine. +- See the list of providers for zkSync [docs](https://v2-docs.zksync.io/dev/fundamentals/testnet.md). For this tutorial we will use `https://zksync2-testnet.zksync.dev` +- Set the chain ID to `280` (the correct ID for the zkSync testnet) +- Merge the custom config created above with the generated `evmconnect` config file To do this, run the following command: + ``` ff init zksync 1\ --multiparty=false \ @@ -63,6 +52,7 @@ ff init zksync 1\ ``` ## Start the stack + Now you should be able to start your stack by running: ``` @@ -82,6 +72,7 @@ ff logs zksync ``` ## Get some ETH + At this point you should have a working FireFly stack, talking to a public chain. However, you won't be able to run any transactions just yet, because you don't have any way to pay for gas. zkSync does not currently have its own native token and instead uses Ethereum for transaction. A testnet faucet can give us some ETH. First, you will need to know what signing address your FireFly node is using. To check that, you can run: @@ -101,9 +92,11 @@ Copy your zkSync address and go to the [Goerli Ethereum faucet](https://www.allt ![Goerli Faucet](images/zksync_faucet.png) ### Confirm the transaction on the Etherscan Explorer + You should be able to go lookup your account at [https://etherscan.io/](https://etherscan.io/) and see that you now have a balance of 0.025 ETH. Simply paste in your account address to search for it. ![Etherscan](images/zksync_explorer.png) ## Use the public testnet -Now that you have everything set up, you can follow one of the other FireFly guides such as [Using Tokens](../tokens/index.md) or [Custom Smart Contracts](../custom_contracts/ethereum.md). For detailed instructions on deploying a custom smart contract to zkSync, please see the [zkSync docs](https://docs.zksync.io/dev/contracts/) for instructions using various tools. \ No newline at end of file + +Now that you have everything set up, you can follow one of the other FireFly guides such as [Using Tokens](../tokens/index.md) or [Custom Smart Contracts](../custom_contracts/ethereum.md). For detailed instructions on deploying a custom smart contract to zkSync, please see the [zkSync docs](https://docs.zksync.io/dev/contracts/) for instructions using various tools. diff --git a/docs/tutorials/create_custom_identity.md b/doc-site/docs/tutorials/create_custom_identity.md similarity index 92% rename from docs/tutorials/create_custom_identity.md rename to doc-site/docs/tutorials/create_custom_identity.md index 41d2dd1c5..6524ef93b 100644 --- a/docs/tutorials/create_custom_identity.md +++ b/doc-site/docs/tutorials/create_custom_identity.md @@ -1,20 +1,8 @@ --- -layout: default title: Create a custom identity -parent: pages.tutorials -nav_order: 8 --- # Create a Custom Identity -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- ## Quick reference @@ -22,14 +10,14 @@ Out of the box, a FireFly Supernode contains both an `org` and a `node` identity ## Additional info -- Reference: [Identities](../reference//identities.md) +- Reference: [Identities](../reference/identities.md) - Swagger: POST /api/v1/identities ## Previous steps: Start your environment -If you haven't started a FireFly stack already, please go to the Getting Started guide on how to [Start your environment](../../gettingstarted/setup_env.md) +If you haven't started a FireFly stack already, please go to the Getting Started guide on how to [Start your environment](../gettingstarted/setup_env.md) -[← β‘‘ Start your environment](../../gettingstarted/setup_env.md){: .btn .btn-purple .mb-5} +[← β‘‘ Start your environment](../gettingstarted/setup_env.md){: .md-button .md-button--primary} ## Step 1: Create a new account diff --git a/docs/tutorials/custom_contracts/ethereum.md b/doc-site/docs/tutorials/custom_contracts/ethereum.md similarity index 98% rename from docs/tutorials/custom_contracts/ethereum.md rename to doc-site/docs/tutorials/custom_contracts/ethereum.md index bcf79993c..876219a58 100644 --- a/docs/tutorials/custom_contracts/ethereum.md +++ b/doc-site/docs/tutorials/custom_contracts/ethereum.md @@ -1,25 +1,12 @@ --- -layout: default title: Ethereum -parent: pages.custom_smart_contracts -grand_parent: pages.tutorials -nav_order: 1 --- # Work with Ethereum smart contracts -{: .no_toc } This guide describes the steps to deploy a smart contract to an Ethereum blockchain and use FireFly to interact with it in order to submit transactions, query for states and listening for events. -> **NOTE:** This guide assumes that you are running a local FireFly stack with at least 2 members and an Ethereum blockchain created by the FireFly CLI. If you need help getting that set up, please see the [Getting Started guide to Start your environment](../../gettingstarted/setup_env.html). - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- +> **NOTE:** This guide assumes that you are running a local FireFly stack with at least 2 members and an Ethereum blockchain created by the FireFly CLI. If you need help getting that set up, please see the [Getting Started guide to Start your environment](../../gettingstarted/setup_env.md). ## Example smart contract @@ -55,7 +42,7 @@ contract SimpleStorage { If you need to deploy an Ethereum smart contract with a signing key that FireFly will use for submitting future transactions it is recommended to use FireFly's built in contract deployment API. This is useful in many cases. For example, you may want to deploy a token contract and have FireFly mint some tokens. Many token contracts only allow the contract deployer to mint, so the contract would need to be deployed with a FireFly signing key. -You will need compile the contract yourself using [solc](https://docs.soliditylang.org/en/latest/installing-solidity.html) or some other tool. After you have compiled the contract, look in the JSON output file for the fields to build the request below. +You will need compile the contract yourself using [solc](https://docs.soliditylang.org/en/latest/installing-solidity.md) or some other tool. After you have compiled the contract, look in the JSON output file for the fields to build the request below. ### Request diff --git a/docs/tutorials/custom_contracts/fabric.md b/doc-site/docs/tutorials/custom_contracts/fabric.md similarity index 95% rename from docs/tutorials/custom_contracts/fabric.md rename to doc-site/docs/tutorials/custom_contracts/fabric.md index e7f2df33b..d4b670de7 100644 --- a/docs/tutorials/custom_contracts/fabric.md +++ b/doc-site/docs/tutorials/custom_contracts/fabric.md @@ -1,26 +1,12 @@ --- -layout: default title: Fabric -parent: pages.custom_smart_contracts -grand_parent: pages.tutorials -nav_order: 2 --- # Work with Hyperledger Fabric chaincodes -{: .no_toc } - This guide describes the steps to deploy a chaincode to a Hyperledger Fabric blockchain and use FireFly to interact with it in order to submit transactions, query for states and listening for events. -> **NOTE:** This guide assumes that you are running a local FireFly stack with at least 2 members and a Fabric blockchain created by the FireFly CLI. If you need help getting that set up, please see the [Getting Started guide to Start your environment](../../gettingstarted/setup_env.html). - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- +> **NOTE:** This guide assumes that you are running a local FireFly stack with at least 2 members and a Fabric blockchain created by the FireFly CLI. If you need help getting that set up, please see the [Getting Started guide to Start your environment](../../gettingstarted/setup_env.md). ## Example smart contract @@ -369,11 +355,12 @@ We will use the FFI JSON constructed above and `POST` that to the `/contracts/in ``` > **NOTE**: We can broadcast this contract interface conveniently with the help of FireFly Sandbox running at `http://127.0.0.1:5108` -* Go to the `Contracts Section` -* Click on `Define a Contract Interface` -* Select `FFI - FireFly Interface` in the `Interface Fromat` dropdown -* Copy the `FFI JSON` crafted by you into the `Schema` Field -* Click on `Run` + +- Go to the `Contracts Section` +- Click on `Define a Contract Interface` +- Select `FFI - FireFly Interface` in the `Interface Fromat` dropdown +- Copy the `FFI JSON` crafted by you into the `Schema` Field +- Click on `Run` ## Create an HTTP API for the contract @@ -423,14 +410,16 @@ We need to copy the `id` field we got in the response from the previous step to } } ``` + > **NOTE**: We can create this Http API conveniently with the help of FireFly Sandbox running at `http://127.0.0.1:5108` -* Go to the `Contracts Section` -* Click on `Register a Contract API` -* Select the name of your broadcasted FFI in the `Contract Interface` dropdown -* In the `Name` Field, give a name that will be part of the URL for your Http API -* In the `Chaincode` Field, give your chaincode name for which you wrote the FFI -* In the `Channel` Field, give the channel name where your chaincode is deployed -* Click on `Run` + +- Go to the `Contracts Section` +- Click on `Register a Contract API` +- Select the name of your broadcasted FFI in the `Contract Interface` dropdown +- In the `Name` Field, give a name that will be part of the URL for your Http API +- In the `Chaincode` Field, give your chaincode name for which you wrote the FFI +- In the `Channel` Field, give the channel name where your chaincode is deployed +- Click on `Run` ## View OpenAPI spec for the contract @@ -722,7 +711,13 @@ After creating the subscription, you should see an event arrive on the connected "name": "AssetCreated", "listener": "6e7f5dd8-5a57-4163-a1d2-5654e784dc31", "protocolId": "000000000015/000000/000000", - "output": { "AppraisedValue": 12300, "Color": "red", "ID": "asset-01", "Owner": "Jerry", "Size": 10 }, + "output": { + "AppraisedValue": 12300, + "Color": "red", + "ID": "asset-01", + "Owner": "Jerry", + "Size": 10 + }, "info": { "blockNumber": 15, "chaincodeId": "asset_transfer", @@ -734,9 +729,16 @@ After creating the subscription, you should see an event arrive on the connected "transactionIndex": 0 }, "timestamp": "2022-05-02T17:26:54.9209723Z", - "tx": { "type": "", "blockchainId": "172637bf59a3520ca6dd02f716e1043ba080e10e1cd2f98b4e6b85abcc6a6d69" } + "tx": { + "type": "", + "blockchainId": "172637bf59a3520ca6dd02f716e1043ba080e10e1cd2f98b4e6b85abcc6a6d69" + } }, - "subscription": { "id": "06d18b49-e763-4f5c-9e97-c25024fe57c8", "namespace": "default", "name": "asset_transfer" } + "subscription": { + "id": "06d18b49-e763-4f5c-9e97-c25024fe57c8", + "namespace": "default", + "name": "asset_transfer" + } } ``` diff --git a/docs/tutorials/custom_contracts/images/simple_storage_swagger.png b/doc-site/docs/tutorials/custom_contracts/images/simple_storage_swagger.png similarity index 100% rename from docs/tutorials/custom_contracts/images/simple_storage_swagger.png rename to doc-site/docs/tutorials/custom_contracts/images/simple_storage_swagger.png diff --git a/docs/tutorials/custom_contracts/images/tezos_contract_deployment.png b/doc-site/docs/tutorials/custom_contracts/images/tezos_contract_deployment.png similarity index 100% rename from docs/tutorials/custom_contracts/images/tezos_contract_deployment.png rename to doc-site/docs/tutorials/custom_contracts/images/tezos_contract_deployment.png diff --git a/docs/tutorials/custom_contracts/images/tezos_contract_deployment2.png b/doc-site/docs/tutorials/custom_contracts/images/tezos_contract_deployment2.png similarity index 100% rename from docs/tutorials/custom_contracts/images/tezos_contract_deployment2.png rename to doc-site/docs/tutorials/custom_contracts/images/tezos_contract_deployment2.png diff --git a/docs/tutorials/custom_contracts/images/tezos_contract_deployment3.png b/doc-site/docs/tutorials/custom_contracts/images/tezos_contract_deployment3.png similarity index 100% rename from docs/tutorials/custom_contracts/images/tezos_contract_deployment3.png rename to doc-site/docs/tutorials/custom_contracts/images/tezos_contract_deployment3.png diff --git a/docs/tutorials/custom_contracts/index.md b/doc-site/docs/tutorials/custom_contracts/index.md similarity index 97% rename from docs/tutorials/custom_contracts/index.md rename to doc-site/docs/tutorials/custom_contracts/index.md index ed8ac56ec..449099a1e 100644 --- a/docs/tutorials/custom_contracts/index.md +++ b/doc-site/docs/tutorials/custom_contracts/index.md @@ -1,9 +1,5 @@ --- -layout: i18n_page -title: pages.custom_smart_contracts -parent: pages.tutorials -nav_order: 7 -has_children: true +title: Work with custom smart contracts --- ## Quick reference @@ -47,3 +43,5 @@ Like the rest of FireFly, custom onchain logic support are implemented with an a ![Smart Contracts Async Flow](../../images/smart_contracts_async_flow.svg "Smart Contracts Async Flow") + + diff --git a/docs/tutorials/custom_contracts/pinning.md b/doc-site/docs/tutorials/custom_contracts/pinning.md similarity index 96% rename from docs/tutorials/custom_contracts/pinning.md rename to doc-site/docs/tutorials/custom_contracts/pinning.md index dab7c1549..21eaee8f7 100644 --- a/docs/tutorials/custom_contracts/pinning.md +++ b/doc-site/docs/tutorials/custom_contracts/pinning.md @@ -1,29 +1,15 @@ --- -layout: default title: Pinning Data -parent: pages.custom_smart_contracts -grand_parent: pages.tutorials -nav_order: 4 --- # Pin off-chain data to a custom blockchain transaction -{: .no_toc } - This guide describes how to associate an arbitrary off-chain payload with a blockchain transaction on a contract of your own design. A hash of the payload will be recorded as part of the blockchain transaction, and on the receiving side, FireFly will ensure that both the on-chain and off-chain pieces are received and aggregated together. > **NOTE:** This is an advanced FireFly feature. Before following any of the steps in this guide, you should be very familiar > and comfortable with the basic features of how [broadcast messages](../broadcast_data.md) and [private messages](../private_send.md) > work, be proficient at custom contract development on your blockchain of choice, and understand the -> fundamentals of how FireFly interacts with [custom contracts](../). - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- +> fundamentals of how FireFly interacts with [custom contracts](./index.md). ## Designing a compatible contract diff --git a/doc-site/docs/tutorials/custom_contracts/tezos.md b/doc-site/docs/tutorials/custom_contracts/tezos.md new file mode 100644 index 000000000..02482a889 --- /dev/null +++ b/doc-site/docs/tutorials/custom_contracts/tezos.md @@ -0,0 +1,1020 @@ +--- +title: Tezos +--- + +# Work with Tezos smart contracts + +This guide describes the steps to deploy a smart contract to a Tezos blockchain and use FireFly to interact with it in order to submit transactions, query for states and listening for events. + +## Smart Contract Languages + +Smart contracts on Tezos can be programmed using familiar, developer-friendly languages. All features available on Tezos can be written in any of the high-level languages used to write smart contracts, such as Archetype, LIGO, and SmartPy. These languages all compile down to [Michelson](https://tezos.gitlab.io/active/michelson.html) and you can switch between languages based on your preferences and projects. + +> **NOTE:** For this tutorial we are going to use [SmartPy](https://smartpy.io/) for building Tezos smart contracts utilizing the broadly adopted Python language. + +## Example smart contract + +First let's look at a simple contract smart contract called `SimpleStorage`, which we will be using on a Tezos blockchain. Here we have one state variable called 'storedValue' and initialized with the value 12. During initialization the type of the variable was defined as 'int'. You can see more at [SmartPy types](https://smartpy.io/manual/syntax/integers-and-mutez). And then we added a simple test, which set the storage value to 15 and checks that the value was changed as expected. + +> **NOTE:** Smart contract's tests (marked with `@sp.add_test` annotation) are used to verify the validity of contract entrypoints and do not affect the state of the contract during deployment. + +Here is the source for this contract: + +```smarty +import smartpy as sp + +@sp.module +def main(): + # Declares a new contract + class SimpleStorage(sp.Contract): + # Storage. Persists in between transactions + def __init__(self, value): + self.data.x = value + + # Allows the stored integer to be changed + @sp.entrypoint + def set(self, params): + self.data.x = params.value + + # Returns the currently stored integer + @sp.onchain_view() + def get(self): + return self.data.x + +@sp.add_test() +def test(): + # Create a test scenario + scenario = sp.test_scenario("Test simple storage", main) + scenario.h1("SimpleStorage") + + # Initialize the contract + c = main.SimpleStorage(12) + + # Run some test cases + scenario += c + c.set(value=15) + scenario.verify(c.data.x == 15) + scenario.verify(scenario.compute(c.get()) == 15) +``` + +## Contract deployment via SmartPy IDE + +To deploy the contract, we will use [SmartPy IDE](https://smartpy.io/ide). + +1. Open an IDE; +2. Paste the contract code; +3. Click "Run code" button; +4. Then you will see "Show Michelson" button, click on that; +5. On the opened pop-up click button "Deploy Contract"; +6. Choose the Ghostnet network; +7. Select an account, which you're going to use to deploy the contract; +8. Click "Estimate Cost From RPC" button; +9. Click "Deploy Contract" button; + +![ContractDeployment](images/tezos_contract_deployment.png) +![ContractDeployment2](images/tezos_contract_deployment2.png) +![ContractDeployment3](images/tezos_contract_deployment3.png) + +Here we can see that our new contract address is `KT1ED4gj2xZnp8318yxa5NpvyvW15pqe4yFg`. This is the address that we will reference in the rest of this guide. + +## Contract deployment via HTTP API + +To deploy the contract we can use HTTP API: +`POST` `http://localhost:5000/api/v1/namespaces/default/contracts/deploy` + +```json +{ + "contract": { + "code": [ + { + "prim": "storage", + "args": [ + { + "prim": "int" + } + ] + }, + { + "prim": "parameter", + "args": [ + { + "prim": "int", + "annots": ["%set"] + } + ] + }, + { + "prim": "code", + "args": [ + [ + { + "prim": "CAR" + }, + { + "prim": "NIL", + "args": [ + { + "prim": "operation" + } + ] + }, + { + "prim": "PAIR" + } + ] + ] + }, + { + "prim": "view", + "args": [ + { + "string": "get" + }, + { + "prim": "unit" + }, + { + "prim": "int" + }, + [ + { + "prim": "CDR" + } + ] + ] + } + ], + "storage": { + "int": "12" + } + } +} +``` + +The `contract` field has two fields - `code` with Michelson code of contract and `storage` with initial Storage values. + +The response of request above: + +```json +{ + "id": "0c3810c7-baed-4077-9d2c-af316a4a567f", + "namespace": "default", + "tx": "21d03e6d-d106-48f4-aacd-688bf17b71fd", + "type": "blockchain_deploy", + "status": "Pending", + "plugin": "tezos", + "input": { + "contract": { + "code": [ + { + "args": [ + { + "prim": "int" + } + ], + "prim": "storage" + }, + { + "args": [ + { + "annots": ["%set"], + "prim": "int" + } + ], + "prim": "parameter" + }, + { + "args": [ + [ + { + "prim": "CAR" + }, + { + "args": [ + { + "prim": "operation" + } + ], + "prim": "NIL" + }, + { + "prim": "PAIR" + } + ] + ], + "prim": "code" + }, + { + "args": [ + { + "string": "get" + }, + { + "prim": "unit" + }, + { + "prim": "int" + }, + [ + { + "prim": "CDR" + } + ] + ], + "prim": "view" + } + ], + "storage": { + "int": "12" + } + }, + "definition": null, + "input": null, + "key": "tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31", + "options": null + }, + "created": "2024-04-01T14:20:20.665039Z", + "updated": "2024-04-01T14:20:20.665039Z" +} +``` + +The success result of deploy can be checked by +`GET` `http://localhost:5000/api/v1/namespaces/default/operations/0c3810c7-baed-4077-9d2c-af316a4a567f` +where `0c3810c7-baed-4077-9d2c-af316a4a567f` is operation id from response above. + +The success response: + +```json +{ + "id": "0c3810c7-baed-4077-9d2c-af316a4a567f", + "namespace": "default", + "tx": "21d03e6d-d106-48f4-aacd-688bf17b71fd", + "type": "blockchain_deploy", + "status": "Succeeded", + "plugin": "tezos", + "input": { + "contract": { + "code": [ + { + "args": [ + { + "prim": "int" + } + ], + "prim": "storage" + }, + { + "args": [ + { + "annots": ["%set"], + "prim": "int" + } + ], + "prim": "parameter" + }, + { + "args": [ + [ + { + "prim": "CAR" + }, + { + "args": [ + { + "prim": "operation" + } + ], + "prim": "NIL" + }, + { + "prim": "PAIR" + } + ] + ], + "prim": "code" + }, + { + "args": [ + { + "string": "get" + }, + { + "prim": "unit" + }, + { + "prim": "int" + }, + [ + { + "prim": "CDR" + } + ] + ], + "prim": "view" + } + ], + "storage": { + "int": "12" + } + }, + "definition": null, + "input": null, + "key": "tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31", + "options": null + }, + "output": { + "headers": { + "requestId": "default:0c3810c7-baed-4077-9d2c-af316a4a567f", + "type": "TransactionSuccess" + }, + "protocolId": "ProxfordYmVfjWnRcgjWH36fW6PArwqykTFzotUxRs6gmTcZDuH", + "transactionHash": "ootDut4xxR2yeYz6JuySuyTVZnXgda2t8SYrk3iuJpm531TZuCj" + }, + "created": "2024-04-01T14:20:20.665039Z", + "updated": "2024-04-01T14:20:20.665039Z", + "detail": { + "created": "2024-04-01T14:20:21.928976Z", + "firstSubmit": "2024-04-01T14:20:22.714493Z", + "from": "tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31", + "gasPrice": "0", + "historySummary": [ + { + "count": 1, + "firstOccurrence": "2024-04-01T14:20:21.930764Z", + "lastOccurrence": "2024-04-01T14:20:21.930765Z", + "subStatus": "Received" + }, + { + "action": "AssignNonce", + "count": 2, + "firstOccurrence": "2024-04-01T14:20:21.930767Z", + "lastOccurrence": "2024-04-01T14:20:22.714772Z" + }, + { + "action": "RetrieveGasPrice", + "count": 1, + "firstOccurrence": "2024-04-01T14:20:22.714774Z", + "lastOccurrence": "2024-04-01T14:20:22.714774Z" + }, + { + "action": "SubmitTransaction", + "count": 1, + "firstOccurrence": "2024-04-01T14:20:22.715269Z", + "lastOccurrence": "2024-04-01T14:20:22.715269Z" + }, + { + "action": "ReceiveReceipt", + "count": 1, + "firstOccurrence": "2024-04-01T14:20:29.244396Z", + "lastOccurrence": "2024-04-01T14:20:29.244396Z" + }, + { + "action": "Confirm", + "count": 1, + "firstOccurrence": "2024-04-01T14:20:29.244762Z", + "lastOccurrence": "2024-04-01T14:20:29.244762Z" + } + ], + "id": "default:0c3810c7-baed-4077-9d2c-af316a4a567f", + "lastSubmit": "2024-04-01T14:20:22.714493Z", + "nonce": "23094946", + "policyInfo": {}, + "receipt": { + "blockHash": "BLvWL4t8GbaufGcQwiv3hHCsvgD6qwXfAXofyvojSMoFeGMXMR1", + "blockNumber": "5868268", + "contractLocation": { + "address": "KT1CkTPsgTUQxR3CCpvtrcuQFV5Jf7cJgHFg" + }, + "extraInfo": [ + { + "consumedGas": "584", + "contractAddress": "KT1CkTPsgTUQxR3CCpvtrcuQFV5Jf7cJgHFg", + "counter": null, + "errorMessage": null, + "fee": null, + "from": null, + "gasLimit": null, + "paidStorageSizeDiff": "75", + "status": "applied", + "storage": null, + "storageLimit": null, + "storageSize": "75", + "to": null + } + ], + "protocolId": "ProxfordYmVfjWnRcgjWH36fW6PArwqykTFzotUxRs6gmTcZDuH", + "success": true, + "transactionIndex": "0" + }, + "sequenceId": "018e9a08-582a-01ec-9209-9d79ef742c9b", + "status": "Succeeded", + "transactionData": "c37274b662d68da8fdae2a02ad6c460a79933c70c6fa7500dc98a9ade6822f026d00673bb6e6298063f97940953de23d441ab20bf757f602a3cd810bad05b003000000000041020000003c0500045b00000004257365740501035b050202000000080316053d036d03420991000000130100000003676574036c035b020000000203170000000000000002000c", + "transactionHash": "ootDut4xxR2yeYz6JuySuyTVZnXgda2t8SYrk3iuJpm531TZuCj", + "transactionHeaders": { + "from": "tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31", + "nonce": "23094946" + }, + "updated": "2024-04-01T14:20:29.245172Z" + } +} +``` + +## The FireFly Interface Format + +As we know from the previous section - smart contracts on the Tezos blockchain are using the domain-specific, stack-based programming language called [Michelson](https://tezos.gitlab.io/active/michelson.html). It is a key component of the Tezos platform and plays a fundamental role in defining the behavior of smart contracts and facilitating their execution. +This language is very efficient but also a bit tricky and challenging for learning, so in order to teach FireFly how to interact with the smart contract, we will be using [FireFly Interface (FFI)](../../reference/firefly_interface_format.md) to define the contract inteface which later will be encoded to Michelson. + +### Schema details + +The `details` field is used to encapsulate blockchain specific type information about a specific field. (More details at [schema details](../../reference/firefly_interface_format.md#schema-details)) + +#### Supported Tezos types + +- nat +- integer +- string +- address +- bytes +- boolean +- variant +- list +- struct +- map + +#### Internal type vs Internal schema + +internalType is a field which is used to describe tezos primitive types + +```json +{ + "details": { + "type": "address", + "internalType": "address" + } +} +``` + +internalSchema in turn is used to describe more complex tezos types as list, struct or variant + +Struct example: + +```json +{ + "details": { + "type": "schema", + "internalSchema": { + "type": "struct", + "args": [ + { + "name": "metadata", + "type": "bytes" + }, + { + "name": "token_id", + "type": "nat" + } + ] + } + } +} +``` + +List example: + +```json +{ + "details": { + "type": "schema", + "internalSchema": { + "type": "struct", + "args": [ + { + "name": "metadata", + "type": "bytes" + }, + { + "name": "token_id", + "type": "nat" + } + ] + } + } +} +``` + +Variant example: + +```json +{ + "details": { + "type": "schema", + "internalSchema": { + "type": "variant", + "variants": ["add_operator", "remove_operator"], + "args": [ + { + "type": "struct", + "args": [ + { + "name": "owner", + "type": "address" + }, + { + "name": "operator", + "type": "address" + }, + { + "name": "token_id", + "type": "nat" + } + ] + } + ] + } + } +} +``` + +Map example: + +```json +{ + "details": { + "type": "schema", + "internalSchema": { + "type": "map", + "args": [ + { + "name": "key", + "type": "integer" + }, + { + "name": "value", + "type": "string" + } + ] + } + } +} +``` + +#### Options + +Option type is used to indicate a value as optional (see more at [smartpy options](https://smartpy.io/manual/syntax/options-and-variants#options)) + +```json +{ + "details": { + "type": "string", + "internalType": "string", + "kind": "option" + } +} +``` + +### FA2 example + +The following FFI sample demonstrates the specification for the widely used FA2 (analogue of ERC721 for EVM) smart contract: + +```json +{ + "namespace": "default", + "name": "fa2", + "version": "v1.0.0", + "description": "", + "methods": [ + { + "name": "burn", + "pathname": "", + "description": "", + "params": [ + { + "name": "token_ids", + "schema": { + "type": "array", + "details": { + "type": "nat", + "internalType": "nat" + } + } + } + ], + "returns": [] + }, + { + "name": "destroy", + "pathname": "", + "description": "", + "params": [], + "returns": [] + }, + { + "name": "mint", + "pathname": "", + "description": "", + "params": [ + { + "name": "owner", + "schema": { + "type": "string", + "details": { + "type": "address", + "internalType": "address" + } + } + }, + { + "name": "requests", + "schema": { + "type": "array", + "details": { + "type": "schema", + "internalSchema": { + "type": "struct", + "args": [ + { + "name": "metadata", + "type": "bytes" + }, + { + "name": "token_id", + "type": "nat" + } + ] + } + } + } + } + ], + "returns": [] + }, + { + "name": "pause", + "pathname": "", + "description": "", + "params": [ + { + "name": "pause", + "schema": { + "type": "boolean", + "details": { + "type": "boolean", + "internalType": "boolean" + } + } + } + ], + "returns": [] + }, + { + "name": "select", + "pathname": "", + "description": "", + "params": [ + { + "name": "batch", + "schema": { + "type": "array", + "details": { + "type": "schema", + "internalSchema": { + "type": "struct", + "args": [ + { + "name": "token_id", + "type": "nat" + }, + { + "name": "recipient", + "type": "address" + }, + { + "name": "token_id_start", + "type": "nat" + }, + { + "name": "token_id_end", + "type": "nat" + } + ] + } + } + } + } + ], + "returns": [] + }, + { + "name": "transfer", + "pathname": "", + "description": "", + "params": [ + { + "name": "batch", + "schema": { + "type": "array", + "details": { + "type": "schema", + "internalSchema": { + "type": "struct", + "args": [ + { + "name": "from_", + "type": "address" + }, + { + "name": "txs", + "type": "list", + "args": [ + { + "type": "struct", + "args": [ + { + "name": "to_", + "type": "address" + }, + { + "name": "token_id", + "type": "nat" + }, + { + "name": "amount", + "type": "nat" + } + ] + } + ] + } + ] + } + } + } + } + ], + "returns": [] + }, + { + "name": "update_admin", + "pathname": "", + "description": "", + "params": [ + { + "name": "admin", + "schema": { + "type": "string", + "details": { + "type": "address", + "internalType": "address" + } + } + } + ], + "returns": [] + }, + { + "name": "update_operators", + "pathname": "", + "description": "", + "params": [ + { + "name": "requests", + "schema": { + "type": "array", + "details": { + "type": "schema", + "internalSchema": { + "type": "variant", + "variants": ["add_operator", "remove_operator"], + "args": [ + { + "type": "struct", + "args": [ + { + "name": "owner", + "type": "address" + }, + { + "name": "operator", + "type": "address" + }, + { + "name": "token_id", + "type": "nat" + } + ] + } + ] + } + } + } + } + ], + "returns": [] + } + ], + "events": [] +} +``` + +## Broadcast the contract interface + +Now that we have a FireFly Interface representation of our smart contract, we want to broadcast that to the entire network. This broadcast will be pinned to the blockchain, so we can always refer to this specific name and version, and everyone in the network will know exactly which contract interface we are talking about. + +We will use the FFI JSON constructed above and `POST` that to the `/contracts/interfaces` API endpoint. + +### Request + +`POST` `http://localhost:5000/api/v1/namespaces/default/contracts/interfaces` + +```json +{ + "namespace": "default", + "name": "simplestorage", + "version": "v1.0.0", + "description": "", + "methods": [ + { + "name": "set", + "pathname": "", + "description": "", + "params": [ + { + "name": "newValue", + "schema": { + "type": "integer", + "details": { + "type": "integer", + "internalType": "integer" + } + } + } + ], + "returns": [] + }, + { + "name": "get", + "pathname": "", + "description": "", + "params": [], + "returns": [] + } + ], + "events": [] +} +``` + +### Response + +```json +{ + "id": "f9e34787-e634-46cd-af47-b52c537404ff", + "namespace": "default", + "name": "simplestorage", + "description": "", + "version": "v1.0.0", + "methods": [ + { + "id": "78f13a7f-7b85-47c3-bf51-346a9858c027", + "interface": "f9e34787-e634-46cd-af47-b52c537404ff", + "name": "set", + "namespace": "default", + "pathname": "set", + "description": "", + "params": [ + { + "name": "newValue", + "schema": { + "type": "integer", + "details": { + "type": "integer", + "internalType": "integer" + } + } + } + ], + "returns": [] + }, + { + "id": "ee864e25-c3f7-42d3-aefd-a82f753e9002", + "interface": "f9e34787-e634-46cd-af47-b52c537404ff", + "name": "get", + "namespace": "tezos", + "pathname": "get", + "description": "", + "params": [], + "returns": [] + } + ] +} +``` + +> **NOTE**: We can broadcast this contract interface conveniently with the help of FireFly Sandbox running at `http://127.0.0.1:5108` + +- Go to the `Contracts Section` +- Click on `Define a Contract Interface` +- Select `FFI - FireFly Interface` in the `Interface Fromat` dropdown +- Copy the `FFI JSON` crafted by you into the `Schema` Field +- Click on `Run` + +## Create an HTTP API for the contract + +Now comes the fun part where we see some of the powerful, developer-friendly features of FireFly. The next thing we're going to do is tell FireFly to build an HTTP API for this smart contract, complete with an OpenAPI Specification and Swagger UI. As part of this, we'll also tell FireFly where the contract is on the blockchain. + +Like the interface broadcast above, this will also generate a broadcast which will be pinned to the blockchain so all the members of the network will be aware of and able to interact with this API. + +We need to copy the `id` field we got in the response from the previous step to the `interface.id` field in the request body below. We will also pick a name that will be part of the URL for our HTTP API, so be sure to pick a name that is URL friendly. In this case we'll call it `simple-storage`. Lastly, in the `location.address` field, we're telling FireFly where an instance of the contract is deployed on-chain. + +> **NOTE**: The `location` field is optional here, but if it is omitted, it will be required in every request to invoke or query the contract. This can be useful if you have multiple instances of the same contract deployed to different addresses. + +### Request + +`POST` `http://localhost:5000/api/v1/namespaces/default/apis` + +```json +{ + "name": "simple-storage", + "interface": { + "id": "f9e34787-e634-46cd-af47-b52c537404ff" + }, + "location": { + "address": "KT1ED4gj2xZnp8318yxa5NpvyvW15pqe4yFg" + } +} +``` + +### Response + +```json +{ + "id": "af09de97-741d-4f61-8d30-4db5e7460f76", + "namespace": "default", + "interface": { + "id": "f9e34787-e634-46cd-af47-b52c537404ff" + }, + "location": { + "address": "KT1ED4gj2xZnp8318yxa5NpvyvW15pqe4yFg" + }, + "name": "simple-storage", + "urls": { + "openapi": "http://127.0.0.1:5000/api/v1/namespaces/default/apis/simple-storage/api/swagger.json", + "ui": "http://127.0.0.1:5000/api/v1/namespaces/default/apis/simple-storage/api" + } +} +``` + +## View OpenAPI spec for the contract + +You'll notice in the response body that there are a couple of URLs near the bottom. If you navigate to the one labeled `ui` in your browser, you should see the Swagger UI for your smart contract. + +![Swagger UI](images/simple_storage_swagger.png "Swagger UI") + +## Invoke the smart contract + +Now that we've got everything set up, it's time to use our smart contract! We're going to make a `POST` request to the `invoke/set` endpoint to set the integer value on-chain. Let's set it to the value of `3` right now. + +### Request + +`POST` `http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/invoke/set` + +```json +{ + "input": { + "newValue": 3 + } +} +``` + +### Response + +```json +{ + "id": "87c7ee1b-33d1-46e2-b3f5-8566c14367cf", + "type": "blockchain_invoke", + "status": "Pending", + "..." +} +``` + +You'll notice that we got an ID back with status `Pending`, and that's expected due to the asynchronous programming model of working with smart contracts in FireFly. To see what the value is now, we can query the smart contract. + +## Query the current value + +To make a read-only request to the blockchain to check the current value of the stored integer, we can make a `POST` to the `query/get` endpoint. + +### Request + +`POST` `http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/query/get` + +```json +{} +``` + +### Response + +```json +{ + "3" +} +``` + +> **NOTE:** Some contracts may have queries that require input parameters. That's why the query endpoint is a `POST`, rather than a `GET` so that parameters can be passed as JSON in the request body. This particular function does not have any parameters, so we just pass an empty JSON object. diff --git a/docs/tutorials/define_datatype.md b/doc-site/docs/tutorials/define_datatype.md similarity index 97% rename from docs/tutorials/define_datatype.md rename to doc-site/docs/tutorials/define_datatype.md index a34405b02..fd24901e7 100644 --- a/docs/tutorials/define_datatype.md +++ b/doc-site/docs/tutorials/define_datatype.md @@ -1,20 +1,8 @@ --- -layout: default title: Define a datatype -parent: pages.tutorials -nav_order: 3 --- # Define a datatype -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- ## Quick reference @@ -31,7 +19,7 @@ of datatypes, as is used to broadcast the data itself. ## Additional info -- Key Concepts: [Broadcast / shared data](../overview/multiparty/broadcast.html) +- Key Concepts: [Broadcast / shared data](../overview/multiparty/broadcast.md) - Swagger: POST /api/v1/namespaces/{ns}/datatypes ### Example 1: Broadcast new datatype @@ -165,7 +153,9 @@ time if it does not conform. On other nodes, bad data results in a `message_reje ] } ``` + ## Defining Datatypes using the Sandbox + You can also define a datatype through the [FireFly Sandbox](../gettingstarted/sandbox.md). To get started, open up the Web UI and Sanbox UI for at least one of your members. The URLs for these were printed in your terminal when you started your FireFly stack. diff --git a/docs/tutorials/events.md b/doc-site/docs/tutorials/events.md similarity index 96% rename from docs/tutorials/events.md rename to doc-site/docs/tutorials/events.md index 3d52203f3..829259dbc 100644 --- a/docs/tutorials/events.md +++ b/doc-site/docs/tutorials/events.md @@ -1,20 +1,8 @@ --- -layout: default title: Listen for events -parent: pages.tutorials -nav_order: 5 --- # Listen for events -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- ## Quick reference @@ -36,7 +24,7 @@ We focus on WebSockets in this getting started guide. ## Additional info -- Key Concepts: [Multi-party process flow](../overview/multiparty/multiparty_flow.html) +- Key Concepts: [Multi-party process flow](../overview/multiparty/multiparty_flow.md) - Reference: _coming soon_ ## WebSockets Example 1: Ephemeral subscription with auto-commit @@ -86,9 +74,7 @@ the full data. "author": "0x1d14b65d2dd5c13f6cb6d3dc4aa13c795a8f3b28", "created": "2021-07-02T04:37:40.1257944Z", "namespace": "default", - "topic": [ - "default" - ], + "topic": ["default"], "datahash": "cd6a09a15ccd3e6ed1d67d69fa4773b563f27f17f3eaad611a2792ba945ca34f" }, "hash": "1b6808d2b95b418e54e7bd34593bfa36a002b841ac42f89d00586dac61e8df43", @@ -123,6 +109,7 @@ of data objects as follows: To reliably process messages within your application, you should first set up a subscription. A subscription requests that: + - FireFly keeps a record of the latest event consumed by that application - FireFly only delivers one copy of the event to the application, even when there are multiple active connections @@ -180,7 +167,6 @@ Example connection URL: - `namespace=default` - event listeners are scoped to a namespace - `name=app1` - the subscription name - ## Custom Contract Events If you are interested in learning more about events for custom smart contracts, please see the [Working with custom smart contracts](./custom_contracts/index.md) section. diff --git a/docs/tutorials/private_send.md b/doc-site/docs/tutorials/private_send.md similarity index 96% rename from docs/tutorials/private_send.md rename to doc-site/docs/tutorials/private_send.md index 0677bab0f..1d40c1bf0 100644 --- a/docs/tutorials/private_send.md +++ b/doc-site/docs/tutorials/private_send.md @@ -1,20 +1,8 @@ --- -layout: default title: Privately send data -parent: pages.tutorials -nav_order: 2 --- # Privately send data -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- ## Quick reference @@ -48,7 +36,7 @@ nav_order: 2 ## Additional info -- Key Concepts: [Private data exchange](../overview/multiparty/data_exchange.html) +- Key Concepts: [Private data exchange](../overview/multiparty/data_exchange.md) - Swagger: POST /api/v1/namespaces/{ns}/messages/private ## Example 1: Pinned private send of in-line string data @@ -200,10 +188,12 @@ on the vast majority of your messages. Here we make two API calls. -1) Create the `data` object explicitly, using a multi-part form upload +1. Create the `data` object explicitly, using a multi-part form upload + - You can also just post JSON to this endpoint -2) Privately send a message referring to that data +2. Privately send a message referring to that data + - The Blob is sent privately to each party - A pin goes to the blockchain - The metadata goes into a batch with the message @@ -262,17 +252,18 @@ Just include a reference to the `id` returned from the upload. "id": "97eb750f-0d0b-4c1d-9e37-1e92d1a22bb8" } ], - "group":{ - "members": [ - { - "identity":"org_1" - } - ] - } + "group": { + "members": [ + { + "identity": "org_1" + } + ] + } } ``` ## Sending Private Messages using the Sandbox + All of the functionality discussed above can be done through the [FireFly Sandbox](../gettingstarted/sandbox.md). To get started, open up the Web UI and Sanbox UI for at least one of your members. The URLs for these were printed in your terminal when you started your FireFly stack. @@ -289,4 +280,4 @@ Click the blue `Run` button. This should return a `202` response immediately in Go back to the FireFly UI (the URL for this would have been shown in the terminal when you started the stack) and you'll see your successful blockchain transaction. Compare the "Recent Network Changes" widget With private messages, your -![Successful Transaction](../images/firefly_first_successful_transaction.png) \ No newline at end of file +![Successful Transaction](../images/firefly_first_successful_transaction.png) diff --git a/docs/tutorials/query_messages.md b/doc-site/docs/tutorials/query_messages.md similarity index 93% rename from docs/tutorials/query_messages.md rename to doc-site/docs/tutorials/query_messages.md index 36a00766c..a221ddd46 100644 --- a/docs/tutorials/query_messages.md +++ b/doc-site/docs/tutorials/query_messages.md @@ -1,20 +1,8 @@ --- -layout: default title: Explore messages -parent: pages.tutorials -nav_order: 5 --- # Explore messages -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- ## Quick reference @@ -28,7 +16,7 @@ This builds on the APIs to query and filter messages, described below ## Additional info -- Reference: [API Query Syntax](../reference/api_query_syntax.html) +- Reference: [API Query Syntax](../reference/api_query_syntax.md) - Swagger: GET /api/v1/namespaces/{ns}/messages ### Example 1: Query confirmed messages @@ -41,7 +29,7 @@ are complete. > _The order in which you process messages should be determined by absolute > order of `message_confirmed` events - queryable via the `events` collection, or > through event listeners (discussed next in the getting started guide)._ -> +> > _That is because `messages` are ordered by timestamp, > which is potentially subject to adjustments of the clock. > Whereas `events` are ordered by the insertion order into the database, and as such @@ -62,9 +50,7 @@ are complete. "created": "2021-07-02T03:09:40.2606238Z", "namespace": "default", "group": "2aa5297b5eed0c3a612a667c727ca38b54fb3b5cc245ebac4c2c7abe490bdf6c", // sent to this group - "topic": [ - "widget_id_12345" - ], + "topic": ["widget_id_12345"], "tag": "new_widget_created", "datahash": "551dd261e80ce76b1908c031cff8a707bd76376d6eddfdc1040c2ed6481ec8dd" }, @@ -98,10 +84,10 @@ are complete. ### Example 2: Query all messages The natural sort order the API will return for messages is: + - Pending messages first - In descending `created` timestamp order - Confirmed messages - In descending `confirmed` timestamp order `GET` `/api/v1/namespaces/{ns}/messages` - diff --git a/docs/tutorials/rotate_dx_certs.md b/doc-site/docs/tutorials/rotate_dx_certs.md similarity index 97% rename from docs/tutorials/rotate_dx_certs.md rename to doc-site/docs/tutorials/rotate_dx_certs.md index 808bf0fff..e9232dd5b 100644 --- a/docs/tutorials/rotate_dx_certs.md +++ b/doc-site/docs/tutorials/rotate_dx_certs.md @@ -1,19 +1,5 @@ --- -layout: i18n_page -title: pages.rotate_dx_certs -parent: pages.tutorials -nav_order: 11 ---- - -# {%t pages.rotate_dx_certs %} -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - +title: Rotate DX Certs --- ## Quick reference diff --git a/docs/tutorials/tokens/erc1155.md b/doc-site/docs/tutorials/tokens/erc1155.md similarity index 91% rename from docs/tutorials/tokens/erc1155.md rename to doc-site/docs/tutorials/tokens/erc1155.md index 6f342d70b..00e6fb89e 100644 --- a/docs/tutorials/tokens/erc1155.md +++ b/doc-site/docs/tutorials/tokens/erc1155.md @@ -1,49 +1,42 @@ --- -layout: default -layout: default title: ERC-1155 -parent: Use tokens -grand_parent: pages.tutorials -nav_order: 3 --- # Use ERC-1155 tokens -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- ## Previous steps: Install the FireFly CLI + If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to [Install the FireFly CLI](../../gettingstarted/firefly_cli.md). -[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .btn .btn-purple .mb-5} +[← β‘  Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .md-button .md-button--primary} ## Create a stack with an ERC-1155 connector + The default token connector that the FireFly CLI sets up is for ERC-20 and ERC-721. If you would like to work with ERC-1155 tokens, you need to create a stack that is configured to use that token connector. To do that, run: + ``` ff init ethereum -t erc-1155 ``` Then run: + ``` ff start ``` ## About the sample token contract + When the FireFly CLI set up your FireFly stack, it also deployed a sample ERC-1155 contract that conforms to the expectations of the token connector. When you create a token pool through FireFly's token APIs, that contract will be used by default.
⚠️ WARNING: The default token contract that was deployed by the FireFly CLI is only provided for the purpose of learning about FireFly. It is not a production grade contract. If you intend to deploy a production application using tokens on FireFly, you should research token contract best practices. For details, please see the source code for the contract that was deployed.
## Use the Sandbox (optional) + At this point you could open the Sandbox at [http://127.0.0.1:5109/home?action=tokens.pools](http://127.0.0.1:5109/home?action=tokens.pools) and perform the functions outlined in the rest of this guide. Or you can keep reading to learn how to build HTTP requests to work with tokens in FireFly. -![Tokens Sandbox](../../images/sandbox/sandbox_token_pool.png) +![Tokens Sandbox](../../images/sandbox/sandbox_token_pool.png) ## Create a pool (using default token contract) + After your stack is up and running, the first thing you need to do is create a token pool. Every application will need at least one token pool. At a minimum, you must always specify a `name` and `type` (`fungible` or `nonfungible`) for the pool. `POST` `http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools` @@ -56,11 +49,13 @@ After your stack is up and running, the first thing you need to do is create a t ``` Other parameters: + - You must specify a `connector` if you have configured multiple token connectors - You may pass through a `config` object of additional parameters, if supported by your token connector - You may specify a `key` understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity ## Create a pool (from a deployed token contract) + If you wish to use a contract that is already on the chain, it is recommended that you first upload the ABI for your specific contract by [creating a FireFly contract interface](../custom_contracts/ethereum.md). This step is optional if you're certain that your ERC-1155 ABI conforms to the default expectations of the token connector, but is generally recommended. See the [README](https://github.com/hyperledger/firefly-tokens-erc1155/blob/main/README.md) of the token connector for details on what contract variants can currently be understood. @@ -96,6 +91,7 @@ only the creator of a pool is allowed to mint - but each contract may define its ``` Other parameters: + - You must specify a `pool` name if you've created more than one pool - You may specify a `key` understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity - You may specify `to` if you'd like to send the minted tokens to a specific identity (default is the same as `key`) @@ -118,6 +114,7 @@ own permission model. > **NOTE:** When transferring a non-fungible token, the amount must always be `1`. The `tokenIndex` field is also required when transferring a non-fungible token. Other parameters: + - You must specify a `pool` name if you've created more than one pool - You may specify a `key` understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity - You may specify `from` if you'd like to send tokens from a specific identity (default is the same as `key`) @@ -135,35 +132,43 @@ when the transaction is submitted. All recipients of the message will then be ab `POST` `http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers` ### Broadcast message + ```json { "amount": 1, "to": "0x07eab7731db665caf02bc92c286f51dea81f923f", "message": { - "data": [{ - "value": "payment for goods" - }] + "data": [ + { + "value": "payment for goods" + } + ] } } ``` ### Private message + ```json { "amount": 1, "to": "0x07eab7731db665caf02bc92c286f51dea81f923f", "message": { "header": { - "type": "transfer_private", + "type": "transfer_private" }, "group": { - "members": [{ + "members": [ + { "identity": "org_1" - }] + } + ] }, - "data": [{ - "value": "payment for goods" - }] + "data": [ + { + "value": "payment for goods" + } + ] } } ``` @@ -180,18 +185,20 @@ burn it - but each connector may define its own permission model. ```json { - "amount": 1, + "amount": 1 } ``` > **NOTE:** When burning a non-fungible token, the amount must always be `1`. The `tokenIndex` field is also required when burning a non-fungible token. Other parameters: + - You must specify a `pool` name if you've created more than one pool - You may specify a `key` understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity - You may specify `from` if you'd like to burn tokens from a specific identity (default is the same as `key`) ## Token approvals + You can also approve other wallets to transfer tokens on your behalf with the `/approvals` API. The important fields in a token approval API request are as follows: - `approved`: Sets whether another account is allowed to transfer tokens out of this wallet or not. If not specified, will default to `true`. Setting to `false` can revoke an existing approval. @@ -201,7 +208,9 @@ You can also approve other wallets to transfer tokens on your behalf with the `/ Here is an example request that would let the signing account `0x634ee8c7d0894d086c7af1fc8514736aed251528` transfer any amount of tokens from my wallet #### Request + `POST` `http://127.0.0.1:5000/api/v1/namespaces/default/tokens/approvals` + ```json { "operator": "0x634ee8c7d0894d086c7af1fc8514736aed251528" @@ -209,17 +218,18 @@ Here is an example request that would let the signing account `0x634ee8c7d0894d0 ``` #### Response + ```json { - "localId": "46fef50a-cf93-4f92-acf8-fae161b37362", - "pool": "e1477ed5-7282-48e5-ad9d-1612296bb29d", - "connector": "erc1155", - "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", - "operator": "0x634ee8c7d0894d086c7af1fc8514736aed251528", - "approved": true, - "tx": { - "type": "token_approval", - "id": "00faa011-f42c-403d-a047-2df7318967cd" - } + "localId": "46fef50a-cf93-4f92-acf8-fae161b37362", + "pool": "e1477ed5-7282-48e5-ad9d-1612296bb29d", + "connector": "erc1155", + "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", + "operator": "0x634ee8c7d0894d086c7af1fc8514736aed251528", + "approved": true, + "tx": { + "type": "token_approval", + "id": "00faa011-f42c-403d-a047-2df7318967cd" + } } ``` diff --git a/docs/tutorials/tokens/erc20.md b/doc-site/docs/tutorials/tokens/erc20.md similarity index 78% rename from docs/tutorials/tokens/erc20.md rename to doc-site/docs/tutorials/tokens/erc20.md index 3953b7c4d..51fe7ec3a 100644 --- a/docs/tutorials/tokens/erc20.md +++ b/doc-site/docs/tutorials/tokens/erc20.md @@ -1,42 +1,34 @@ --- -layout: default title: ERC-20 -parent: Use tokens -grand_parent: pages.tutorials -nav_order: 1 --- # Use ERC-20 tokens -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- ## Previous steps: Start your environment + If you haven't started a FireFly stack already, please go to the Getting Started guide on how to [Start your environment](../../gettingstarted/setup_env.md). This will set up a token connector that works with both ERC-20 and ERC-721 by default. -[← β‘‘ Start your environment](../../gettingstarted/setup_env.md){: .btn .btn-purple .mb-5} +[← β‘‘ Start your environment](../../gettingstarted/setup_env.md){: .md-button .md-button--primary} ## About the sample token contracts + If you are using the default ERC-20 / ERC-721 token connector, when the FireFly CLI set up your FireFly stack, it also deployed a token factory contract. When you create a token pool through FireFly's token APIs, the token factory contract will automatically deploy an ERC-20 or ERC-721 contract, based on the pool `type` in the API request.
⚠️ WARNING: The default token contract that was deployed by the FireFly CLI is only provided for the purpose of learning about FireFly. It is not a production grade contract. If you intend to deploy a production application using tokens on FireFly, you should research token contract best practices. For details, please see the source code for the contract that was deployed.
## Use the Sandbox (optional) + At this point you could open the Sandbox at [http://127.0.0.1:5109/home?action=tokens.pools](http://127.0.0.1:5109/home?action=tokens.pools) and perform the functions outlined in the rest of this guide. Or you can keep reading to learn how to build HTTP requests to work with tokens in FireFly. -![Tokens Sandbox](../../images/sandbox/sandbox_token_pool.png) +![Tokens Sandbox](../../images/sandbox/sandbox_token_pool.png) ## Create a pool (using default token factory) + After your stack is up and running, the first thing you need to do is create a token pool. Every application will need at least one token pool. At a minimum, you must always specify a `name` and `type` for the pool. If you're using the default ERC-20 / ERC-721 token connector and its sample token factory, it will automatically deploy a new ERC-20 contract instance. #### Request + `POST` `http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools` ```json @@ -47,22 +39,24 @@ If you're using the default ERC-20 / ERC-721 token connector and its sample toke ``` #### Response + ```json { - "id": "e1477ed5-7282-48e5-ad9d-1612296bb29d", - "type": "fungible", - "namespace": "default", - "name": "testpool", - "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", - "connector": "erc20_erc721", - "tx": { - "type": "token_pool", - "id": "e901921e-ffc4-4776-b20a-9e9face70a47" - } + "id": "e1477ed5-7282-48e5-ad9d-1612296bb29d", + "type": "fungible", + "namespace": "default", + "name": "testpool", + "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", + "connector": "erc20_erc721", + "tx": { + "type": "token_pool", + "id": "e901921e-ffc4-4776-b20a-9e9face70a47" + } } ``` Other parameters: + - You must specify a `connector` if you have configured multiple token connectors - You may pass through a `config` object of additional parameters, if supported by your token connector - You may specify a `key` understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity @@ -72,35 +66,38 @@ Other parameters: To lookup the address of the new contract, you can lookup the token pool by its ID on the API. Creating the token pool will also emit an event which will contain the address. To query the token pool you can make a `GET` request to the pool's ID: #### Request + `GET` `http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools/5811e8d5-52d0-44b1-8b75-73f5ff88f598` #### Response + ```json { - "id": "e1477ed5-7282-48e5-ad9d-1612296bb29d", - "type": "fungible", - "namespace": "default", + "id": "e1477ed5-7282-48e5-ad9d-1612296bb29d", + "type": "fungible", + "namespace": "default", + "name": "testpool", + "standard": "ERC20", + "locator": "address=0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c&schema=ERC20WithData&type=fungible", + "decimals": 18, + "connector": "erc20_erc721", + "message": "7e2f6004-31fd-4ba8-9845-15c5fe5fbcd7", + "state": "confirmed", + "created": "2022-04-28T14:03:16.732222381Z", + "info": { + "address": "0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c", "name": "testpool", - "standard": "ERC20", - "locator": "address=0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c&schema=ERC20WithData&type=fungible", - "decimals": 18, - "connector": "erc20_erc721", - "message": "7e2f6004-31fd-4ba8-9845-15c5fe5fbcd7", - "state": "confirmed", - "created": "2022-04-28T14:03:16.732222381Z", - "info": { - "address": "0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c", - "name": "testpool", - "schema": "ERC20WithData" - }, - "tx": { - "type": "token_pool", - "id": "e901921e-ffc4-4776-b20a-9e9face70a47" - } + "schema": "ERC20WithData" + }, + "tx": { + "type": "token_pool", + "id": "e901921e-ffc4-4776-b20a-9e9face70a47" + } } ``` ## Create a pool (from a deployed token contract) + If you wish to index and use a contract that is already on the chain, it is recommended that you first upload the ABI for your specific contract by [creating a FireFly contract interface](../custom_contracts/ethereum.md). This step is optional if you're certain that your ERC-20 ABI conforms to the default expectations of the token connector, but is generally recommended. See the [README](https://github.com/hyperledger/firefly-tokens-erc20-erc721/blob/main/README.md) of the token connector for details on what contract variants can currently be understood. @@ -108,6 +105,7 @@ See the [README](https://github.com/hyperledger/firefly-tokens-erc20-erc721/blob You can pass a `config` object with an `address` and `blockNumber` when you make the request to create the token pool, and if you created a contract interface, you can include the `interface` ID as well. #### Request + `POST` `http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools` ```json @@ -131,7 +129,9 @@ Once you have a token pool, you can mint tokens within it. When using the sample > **NOTE:** The default sample contract uses 18 decimal places. This means that if you want to create 100 tokens, the number submitted to the API / blockchain should actually be 100Γ—1018 = `100000000000000000000`. This allows users to work with "fractional" tokens even though Ethereum virtual machines only support integer arithmetic. #### Request + `POST` `http://127.0.0.1:5000/api/v1/namespaces/default/tokens/mint` + ```json { "amount": "100000000000000000000" @@ -139,24 +139,26 @@ Once you have a token pool, you can mint tokens within it. When using the sample ``` #### Response + ```json { - "type": "mint", - "localId": "835fe2a1-594b-4336-bc1d-b2f59d51064b", - "pool": "e1477ed5-7282-48e5-ad9d-1612296bb29d", - "connector": "erc20_erc721", - "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", - "from": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", - "to": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", - "amount": "100000000000000000000", - "tx": { - "type": "token_transfer", - "id": "3fc97e24-fde1-4e80-bd82-660e479c0c43" - } + "type": "mint", + "localId": "835fe2a1-594b-4336-bc1d-b2f59d51064b", + "pool": "e1477ed5-7282-48e5-ad9d-1612296bb29d", + "connector": "erc20_erc721", + "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", + "from": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", + "to": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", + "amount": "100000000000000000000", + "tx": { + "type": "token_transfer", + "id": "3fc97e24-fde1-4e80-bd82-660e479c0c43" + } } ``` Other parameters: + - You must specify a `pool` name if you've created more than one pool - You may specify a `key` understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity - You may specify `to` if you'd like to send the minted tokens to a specific identity (default is the same as `key`) @@ -166,7 +168,9 @@ Other parameters: You may transfer tokens within a pool by specifying an amount and a destination understood by the connector (i.e. an Ethereum address). With the default sample contract, only the owner of the tokens or another approved account may transfer their tokens, but a different contract may define its own permission model. #### Request + `POST` `http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers` + ```json { "amount": "10000000000000000000", @@ -175,24 +179,26 @@ You may transfer tokens within a pool by specifying an amount and a destination ``` #### Response + ```json { - "type": "transfer", - "localId": "61f0a71f-712b-4778-8b37-784fbee52657", - "pool": "e1477ed5-7282-48e5-ad9d-1612296bb29d", - "connector": "erc20_erc721", - "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", - "from": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", - "to": "0xa4222a4ae19448d43a338e6586edd5fb2ac398e1", - "amount": "10000000000000000000", - "tx": { - "type": "token_transfer", - "id": "c0c316a3-23a9-42f3-89b3-1cfdba6c948d" - } + "type": "transfer", + "localId": "61f0a71f-712b-4778-8b37-784fbee52657", + "pool": "e1477ed5-7282-48e5-ad9d-1612296bb29d", + "connector": "erc20_erc721", + "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", + "from": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", + "to": "0xa4222a4ae19448d43a338e6586edd5fb2ac398e1", + "amount": "10000000000000000000", + "tx": { + "type": "token_transfer", + "id": "c0c316a3-23a9-42f3-89b3-1cfdba6c948d" + } } ``` Other parameters: + - You must specify a `pool` name if you've created more than one pool - You may specify a `key` understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity - You may specify `from` if you'd like to send tokens from a specific identity (default is the same as `key`) @@ -210,35 +216,43 @@ when the transaction is submitted. All recipients of the message will then be ab `POST` `http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers` ### Broadcast message + ```json { "amount": 1, "to": "0x07eab7731db665caf02bc92c286f51dea81f923f", "message": { - "data": [{ - "value": "payment for goods" - }] + "data": [ + { + "value": "payment for goods" + } + ] } } ``` ### Private message + ```json { "amount": 1, "to": "0x07eab7731db665caf02bc92c286f51dea81f923f", "message": { "header": { - "type": "transfer_private", + "type": "transfer_private" }, "group": { - "members": [{ + "members": [ + { "identity": "org_1" - }] + } + ] }, - "data": [{ - "value": "payment for goods" - }] + "data": [ + { + "value": "payment for goods" + } + ] } } ``` @@ -255,16 +269,16 @@ another approved account may burn it, but a different contract may define its ow ```json { - "amount": 1, + "amount": 1 } ``` Other parameters: + - You must specify a `pool` name if you've created more than one pool - You may specify a `key` understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity - You may specify `from` if you'd like to burn tokens from a specific identity (default is the same as `key`) - ## Token approvals You can also approve other wallets to transfer tokens on your behalf with the `/approvals` API. The important fields in a token approval API request are as follows: @@ -277,48 +291,53 @@ You can also approve other wallets to transfer tokens on your behalf with the `/ Here is an example request that would let the signing account `0x634ee8c7d0894d086c7af1fc8514736aed251528` transfer up to 10Γ—1018 (`10000000000000000000`) tokens from my wallet #### Request + `POST` `http://127.0.0.1:5000/api/v1/namespaces/default/tokens/approvals` + ```json { "operator": "0x634ee8c7d0894d086c7af1fc8514736aed251528", "config": { - "allowance": "10000000000000000000" + "allowance": "10000000000000000000" } } ``` #### Response + ```json { - "localId": "46fef50a-cf93-4f92-acf8-fae161b37362", - "pool": "e1477ed5-7282-48e5-ad9d-1612296bb29d", - "connector": "erc20_erc721", - "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", - "operator": "0x634ee8c7d0894d086c7af1fc8514736aed251528", - "approved": true, - "tx": { - "type": "token_approval", - "id": "00faa011-f42c-403d-a047-2df7318967cd" - }, - "config": { - "allowance": "10000000000000000000" - } + "localId": "46fef50a-cf93-4f92-acf8-fae161b37362", + "pool": "e1477ed5-7282-48e5-ad9d-1612296bb29d", + "connector": "erc20_erc721", + "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", + "operator": "0x634ee8c7d0894d086c7af1fc8514736aed251528", + "approved": true, + "tx": { + "type": "token_approval", + "id": "00faa011-f42c-403d-a047-2df7318967cd" + }, + "config": { + "allowance": "10000000000000000000" + } } ``` ## Use Metamask + Now that you have an ERC-20 contract up and running, you may be wondering how to use Metamask (or some other wallet) with this contract. This section will walk you through how to connect Metamask to the blockchain and token contract that FireFly is using. ### Configure a new network + The first thing we need to do is tell Metamask how to connect to our local blockchain node. To do that: - Click your account icon - In the drop down menu, click **Settings** -![Metamask Settings](../../images/metamask/settings.png) + ![Metamask Settings](../../images/metamask/settings.png) - On the left hand side of the page, click **Networks** - Click the **Add a network** button -![Metamask Add Network](../../images/metamask/add_network.png) + ![Metamask Add Network](../../images/metamask/add_network.png) - Fill in the network details: - Network Name: `FireFly` (could be any name) @@ -326,13 +345,14 @@ The first thing we need to do is tell Metamask how to connect to our local block - Chain ID: `2021` - Currency Symbol: ETH - Click **Save** -![Metamask Network Details](../../images/metamask/network_details.png) + ![Metamask Network Details](../../images/metamask/network_details.png) ### Import tokens + Metamask won't know about our custom ERC-20 contract until we give it the Ethereum address for the contract, so that's what we'll do next. - Click on **Import tokens** -![Metamask Import Tokens](../../images/metamask/import_tokens.png) + ![Metamask Import Tokens](../../images/metamask/import_tokens.png) - Enter the Ethereum address of the contract - Enter a Token Symbol (can be anything you want) @@ -343,6 +363,7 @@ Metamask won't know about our custom ERC-20 contract until we give it the Ethere ![Metamask Import Tokens](../../images/metamask/contract_address.png) ### Transfer tokens + Now you can copy your account address from your Metamask wallet, and perform a transfer from FireFly's API (as described above) to your Metamask address. ![Metamask Account Address](../../images/metamask/account_address.png) @@ -355,4 +376,4 @@ You can also send tokens to a FireFly address or any other Ethereum address from > **NOTE:** You can find the Ethereum addresses for organizations in your FireFly network in the [Network β†’ Organizations page](http://localhost:5000/ui/namespaces/default/network/organizations) in the FireFly explorer. Click on an organization and look under the Verifiers header for the organization's Ethereum address. -![Metamask Send Tokens](../../images/metamask/send_tokens.png) \ No newline at end of file +![Metamask Send Tokens](../../images/metamask/send_tokens.png) diff --git a/docs/tutorials/tokens/erc721.md b/doc-site/docs/tutorials/tokens/erc721.md similarity index 78% rename from docs/tutorials/tokens/erc721.md rename to doc-site/docs/tutorials/tokens/erc721.md index 3a6763467..a15ce10c8 100644 --- a/docs/tutorials/tokens/erc721.md +++ b/doc-site/docs/tutorials/tokens/erc721.md @@ -1,68 +1,62 @@ --- -layout: default title: ERC-721 -parent: Use tokens -grand_parent: pages.tutorials -nav_order: 2 --- # Use ERC-721 tokens -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- ## Previous steps: Start your environment + If you haven't started a FireFly stack already, please go to the Getting Started guide on how to [Start your environment](../../gettingstarted/setup_env.md). This will set up a token connector that works with both ERC-20 and ERC-721 by default. -[← β‘‘ Start your environment](../../gettingstarted/setup_env.md){: .btn .btn-purple .mb-5} +[← β‘‘ Start your environment](../../gettingstarted/setup_env.md){: .md-button .md-button--primary} ## About the sample token contracts + If you are using the default ERC-20 / ERC-721 token connector, when the FireFly CLI set up your FireFly stack, it also deployed a token factory contract. When you create a token pool through FireFly's token APIs, the token factory contract will automatically deploy an ERC-20 or ERC-721 contract, based on the pool `type` in the API request.
⚠️ WARNING: The default token contract that was deployed by the FireFly CLI is only provided for the purpose of learning about FireFly. It is not a production grade contract. If you intend to deploy a production application using tokens on FireFly, you should research token contract best practices. For details, please see the source code for the contract that was deployed.
## Use the Sandbox (optional) + At this point you could open the Sandbox at [http://127.0.0.1:5109/home?action=tokens.pools](http://127.0.0.1:5109/home?action=tokens.pools) and perform the functions outlined in the rest of this guide. Or you can keep reading to learn how to build HTTP requests to work with tokens in FireFly. -![Tokens Sandbox](../../images/sandbox/sandbox_token_pool.png) +![Tokens Sandbox](../../images/sandbox/sandbox_token_pool.png) ## Create a pool (using default token factory) + After your stack is up and running, the first thing you need to do is create a token pool. Every application will need at least one token pool. At a minimum, you must always specify a `name` and `type` for the pool. If you're using the default ERC-20 / ERC-721 token connector and its sample token factory, it will automatically deploy a new ERC-721 contract instance. #### Request + `POST` `http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools` ```json { - "type": "nonfungible", - "name": "nfts" + "type": "nonfungible", + "name": "nfts" } ``` #### Response + ```json { - "id": "a92a0a25-b886-4b43-931f-4add2840258a", - "type": "nonfungible", - "namespace": "default", - "name": "nfts", - "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", - "connector": "erc20_erc721", - "tx": { - "type": "token_pool", - "id": "00678116-89d2-4295-990c-bd5ffa6e2434" - } + "id": "a92a0a25-b886-4b43-931f-4add2840258a", + "type": "nonfungible", + "namespace": "default", + "name": "nfts", + "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", + "connector": "erc20_erc721", + "tx": { + "type": "token_pool", + "id": "00678116-89d2-4295-990c-bd5ffa6e2434" + } } ``` Other parameters: + - You must specify a `connector` if you have configured multiple token connectors - You may pass through a `config` object of additional parameters, if supported by your token connector - You may specify a `key` understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity @@ -72,34 +66,37 @@ Other parameters: To lookup the address of the new contract, you can lookup the token pool by its ID on the API. Creating the token pool will also emit an event which will contain the address. To query the token pool you can make a `GET` request to the pool's ID: #### Request + `GET` `http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools/5811e8d5-52d0-44b1-8b75-73f5ff88f598` #### Response + ```json { - "id": "a92a0a25-b886-4b43-931f-4add2840258a", - "type": "nonfungible", - "namespace": "default", + "id": "a92a0a25-b886-4b43-931f-4add2840258a", + "type": "nonfungible", + "namespace": "default", + "name": "nfts", + "standard": "ERC721", + "locator": "address=0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c&schema=ERC721WithData&type=nonfungible", + "connector": "erc20_erc721", + "message": "53d95dda-e8ca-4546-9226-a0fdc6ec03ec", + "state": "confirmed", + "created": "2022-04-29T12:03:51.971349509Z", + "info": { + "address": "0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c", "name": "nfts", - "standard": "ERC721", - "locator": "address=0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c&schema=ERC721WithData&type=nonfungible", - "connector": "erc20_erc721", - "message": "53d95dda-e8ca-4546-9226-a0fdc6ec03ec", - "state": "confirmed", - "created": "2022-04-29T12:03:51.971349509Z", - "info": { - "address": "0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c", - "name": "nfts", - "schema": "ERC721WithData" - }, - "tx": { - "type": "token_pool", - "id": "00678116-89d2-4295-990c-bd5ffa6e2434" - } + "schema": "ERC721WithData" + }, + "tx": { + "type": "token_pool", + "id": "00678116-89d2-4295-990c-bd5ffa6e2434" + } } ``` ## Create a pool (from a deployed token contract) + If you wish to index and use a contract that is already on the chain, it is recommended that you first upload the ABI for your specific contract by [creating a FireFly contract interface](../custom_contracts/ethereum.md). This step is optional if you're certain that your ERC-721 ABI conforms to the default expectations of the token connector, but is generally recommended. See the [README](https://github.com/hyperledger/firefly-tokens-erc20-erc721/blob/main/README.md) of the token connector for details on what contract variants can currently be understood. @@ -107,6 +104,7 @@ See the [README](https://github.com/hyperledger/firefly-tokens-erc20-erc721/blob You can pass a `config` object with an `address` and `blockNumber` when you make the request to create the token pool, and if you created a contract interface, you can include the `interface` ID as well. #### Request + `POST` `http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools` ```json @@ -126,14 +124,17 @@ You can pass a `config` object with an `address` and `blockNumber` when you make ## Mint a token Once you have a token pool, you can mint tokens within it. When using the sample contract deployed by the CLI, the following are true: -* only the creator of a pool is allowed to mint within that pool -* the `tokenIndex` must be set to a unique value -* the `amount` must be `1` + +- only the creator of a pool is allowed to mint within that pool +- the `tokenIndex` must be set to a unique value +- the `amount` must be `1` A different ERC-721 contract may define its own requirements. #### Request + `POST` `http://127.0.0.1:5000/api/v1/namespaces/default/tokens/mint` + ```json { "amount": "1", @@ -142,24 +143,26 @@ A different ERC-721 contract may define its own requirements. ``` #### Response + ```json { - "type": "mint", - "localId": "2de2e05e-9474-4a08-a64f-2cceb076bdaa", - "pool": "a92a0a25-b886-4b43-931f-4add2840258a", - "connector": "erc20_erc721", - "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", - "from": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", - "to": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", - "amount": "1", - "tx": { - "type": "token_transfer", - "id": "0fad4581-7cb2-42c7-8f78-62d32205c2c2" - } + "type": "mint", + "localId": "2de2e05e-9474-4a08-a64f-2cceb076bdaa", + "pool": "a92a0a25-b886-4b43-931f-4add2840258a", + "connector": "erc20_erc721", + "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", + "from": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", + "to": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", + "amount": "1", + "tx": { + "type": "token_transfer", + "id": "0fad4581-7cb2-42c7-8f78-62d32205c2c2" + } } ``` Other parameters: + - You must specify a `pool` name if you've created more than one pool - You may specify a `key` understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity - You may specify `to` if you'd like to send the minted tokens to a specific identity (default is the same as `key`) @@ -173,7 +176,9 @@ When transferring an NFT, you must also specify the `tokenIndex` that you wish t > **NOTE:** When transferring NFTs the `amount` must be `1`. If you wish to transfer more NFTs, simply call the endpoint multiple times, specifying the token index of each token to transfer. #### Request + `POST` `http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers` + ```json { "amount": "1", @@ -183,25 +188,27 @@ When transferring an NFT, you must also specify the `tokenIndex` that you wish t ``` #### Response + ```json { - "type": "transfer", - "localId": "f5fd0d13-db13-4d70-9a99-6bcd747f1e42", - "pool": "a92a0a25-b886-4b43-931f-4add2840258a", - "tokenIndex": "1", - "connector": "erc20_erc721", - "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", - "from": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", - "to": "0xa4222a4ae19448d43a338e6586edd5fb2ac398e1", - "amount": "1", - "tx": { - "type": "token_transfer", - "id": "63c1a89b-240c-41eb-84bb-323d56f4ba5a" - } + "type": "transfer", + "localId": "f5fd0d13-db13-4d70-9a99-6bcd747f1e42", + "pool": "a92a0a25-b886-4b43-931f-4add2840258a", + "tokenIndex": "1", + "connector": "erc20_erc721", + "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", + "from": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", + "to": "0xa4222a4ae19448d43a338e6586edd5fb2ac398e1", + "amount": "1", + "tx": { + "type": "token_transfer", + "id": "63c1a89b-240c-41eb-84bb-323d56f4ba5a" + } } ``` Other parameters: + - You must specify a `pool` name if you've created more than one pool - You may specify a `key` understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity - You may specify `from` if you'd like to send tokens from a specific identity (default is the same as `key`) @@ -219,20 +226,24 @@ when the transaction is submitted. All recipients of the message will then be ab `POST` `http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers` ### Broadcast message + ```json { "amount": 1, "tokenIndex": "1", "to": "0x07eab7731db665caf02bc92c286f51dea81f923f", "message": { - "data": [{ - "value": "payment for goods" - }] + "data": [ + { + "value": "payment for goods" + } + ] } } ``` ### Private message + ```json { "amount": 1, @@ -240,16 +251,20 @@ when the transaction is submitted. All recipients of the message will then be ab "to": "0x07eab7731db665caf02bc92c286f51dea81f923f", "message": { "header": { - "type": "transfer_private", + "type": "transfer_private" }, "group": { - "members": [{ + "members": [ + { "identity": "org_1" - }] + } + ] }, - "data": [{ - "value": "payment for goods" - }] + "data": [ + { + "value": "payment for goods" + } + ] } } ``` @@ -258,6 +273,7 @@ Note that all parties in the network will be able to see the transfer (including the recipients of the message will be able to view the actual message data. ## Burn tokens + You may burn a token by specifying the token's `tokenIndex`. With the default sample contract, only the owner of a token or another approved account may burn it, but a different contract may define its own permission model. `POST` `http://127.0.0.1:5000/api/v1/namespaces/default/tokens/burn` @@ -270,11 +286,13 @@ You may burn a token by specifying the token's `tokenIndex`. With the default sa ``` Other parameters: + - You must specify a `pool` name if you've created more than one pool - You may specify a `key` understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity - You may specify `from` if you'd like to burn tokens from a specific identity (default is the same as `key`) ## Token approvals + You can also approve other wallets to transfer tokens on your behalf with the `/approvals` API. The important fields in a token approval API request are as follows: - `approved`: Sets whether another account is allowed to transfer tokens out of this wallet or not. If not specified, will default to `true`. Setting to `false` can revoke an existing approval. @@ -285,48 +303,53 @@ You can also approve other wallets to transfer tokens on your behalf with the `/ Here is an example request that would let the signing account `0x634ee8c7d0894d086c7af1fc8514736aed251528` transfer `tokenIndex` `2` from my wallet. #### Request + `POST` `http://127.0.0.1:5000/api/v1/namespaces/default/tokens/approvals` + ```json { "operator": "0x634ee8c7d0894d086c7af1fc8514736aed251528", "config": { - "tokenIndex": "2" + "tokenIndex": "2" } } ``` #### Response + ```json { - "localId": "46fef50a-cf93-4f92-acf8-fae161b37362", - "pool": "e1477ed5-7282-48e5-ad9d-1612296bb29d", - "connector": "erc20_erc721", - "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", - "operator": "0x634ee8c7d0894d086c7af1fc8514736aed251528", - "approved": true, - "tx": { - "type": "token_approval", - "id": "00faa011-f42c-403d-a047-2df7318967cd" - }, - "config": { - "tokenIndex": "2" - } + "localId": "46fef50a-cf93-4f92-acf8-fae161b37362", + "pool": "e1477ed5-7282-48e5-ad9d-1612296bb29d", + "connector": "erc20_erc721", + "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c", + "operator": "0x634ee8c7d0894d086c7af1fc8514736aed251528", + "approved": true, + "tx": { + "type": "token_approval", + "id": "00faa011-f42c-403d-a047-2df7318967cd" + }, + "config": { + "tokenIndex": "2" + } } ``` ## Use Metamask + Now that you have an ERC-721 contract up and running, you may be wondering how to use Metamask (or some other wallet) with this contract. This section will walk you through how to connect Metamask to the blockchain and token contract that FireFly is using. ### Configure a new network + The first thing we need to do is tell Metamask how to connect to our local blockchain node. To do that: - Click your account icon - In the drop down menu, click **Settings** -![Metamask Settings](../../images/metamask/settings.png) + ![Metamask Settings](../../images/metamask/settings.png) - On the left hand side of the page, click **Networks** - Click the **Add a network** button -![Metamask Add Network](../../images/metamask/add_network.png) + ![Metamask Add Network](../../images/metamask/add_network.png) - Fill in the network details: - Network Name: `FireFly` (could be any name) @@ -334,13 +357,14 @@ The first thing we need to do is tell Metamask how to connect to our local block - Chain ID: `2021` - Currency Symbol: ETH - Click **Save** -![Metamask Network Details](../../images/metamask/network_details.png) + ![Metamask Network Details](../../images/metamask/network_details.png) ### Import tokens + Metamask won't know about our custom ERC-721 contract until we give it the Ethereum address for the contract, so that's what we'll do next. - Click on **Import tokens** -![Metamask Import Tokens](../../images/metamask/import_tokens.png) + ![Metamask Import Tokens](../../images/metamask/import_tokens.png) - Enter the Ethereum address of the contract - Enter a Token Symbol (can be anything you want) @@ -351,6 +375,7 @@ Metamask won't know about our custom ERC-721 contract until we give it the Ether ![Metamask Import Tokens](../../images/metamask/nft_contract_address.png) ### Transfer tokens + Now you can copy your account address from your Metamask wallet, and perform a transfer from FireFly's API (as described above) to your Metamask address. ![Metamask Account Address](../../images/metamask/account_address.png) diff --git a/docs/tutorials/tokens/index.md b/doc-site/docs/tutorials/tokens/index.md similarity index 97% rename from docs/tutorials/tokens/index.md rename to doc-site/docs/tutorials/tokens/index.md index 6133b62be..3ea85c52a 100644 --- a/docs/tutorials/tokens/index.md +++ b/doc-site/docs/tutorials/tokens/index.md @@ -1,12 +1,7 @@ --- -layout: default title: Use tokens -parent: pages.tutorials -nav_order: 6 -has_children: true --- - ## Quick reference Tokens are a critical building block in many blockchain-backed applications. Fungible tokens can represent a store @@ -40,3 +35,5 @@ Ethereum standards: These are provided as examples only - a custom token connector could be backed by any token technology (Ethereum or otherwise) as long as it can support the basic operations described here (create pool, mint, burn, transfer). Other FireFly repos include a sample implementation of a token connector for [ERC-20 and ERC-721](https://github.com/hyperledger/firefly-tokens-erc20-erc721) as well as [ERC-1155](https://github.com/hyperledger/firefly-tokens-erc1155). + + diff --git a/docs/_includes/head_custom.html b/doc-site/docs/versions.json similarity index 100% rename from docs/_includes/head_custom.html rename to doc-site/docs/versions.json diff --git a/doc-site/mkdocs.yml b/doc-site/mkdocs.yml new file mode 100644 index 000000000..b4aced0e1 --- /dev/null +++ b/doc-site/mkdocs.yml @@ -0,0 +1,75 @@ +site_name: Hyperledger FireFly +repo_name: hyperledger/firefly +repo_url: https://github.com/hyperledger/firefly +theme: + name: material + custom_dir: overrides + logo: assets/FireFly_Logo_White.svg + favicon: assets/favicon.ico + icon: + repo: fontawesome/brands/github + palette: + primary: custom + features: + - content.code.copy + - navigation.footer + - navigation.instant + - navigation.top + - navigation.tracking + - navigation.path + - navigation.indexes +extra_css: + - stylesheets/extra.css +markdown_extensions: + - abbr + - admonition + - attr_list + - def_list + - footnotes + - md_in_html + - toc: + permalink: true + toc_depth: 3 + - pymdownx.arithmatex: + generic: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.details + - pymdownx.emoji: + emoji_generator: !!python/name:materialx.emoji.to_svg + emoji_index: !!python/name:materialx.emoji.twemoji + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.magiclink: + repo_url_shorthand: true + user: squidfunk + repo: mkdocs-material + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde +plugins: + - include-markdown: + rewrite_relative_urls: false + - literate-nav + - search + - mike +extra: + analytics: + provider: google + property: !ENV GOOGLE_ANALYTICS_KEY + version: + provider: mike +exclude_docs: | + _includes/ diff --git a/doc-site/overrides/main.html b/doc-site/overrides/main.html new file mode 100644 index 000000000..8d9f50509 --- /dev/null +++ b/doc-site/overrides/main.html @@ -0,0 +1,8 @@ +{% extends "base.html" %} + +{% block outdated %} + You're not viewing the latest version. + + Click here to go to latest. + +{% endblock %} diff --git a/doc-site/requirements.txt b/doc-site/requirements.txt new file mode 100644 index 000000000..20da6741a --- /dev/null +++ b/doc-site/requirements.txt @@ -0,0 +1,4 @@ +mkdocs-material +mkdocs-literate-nav +mkdocs-include-markdown-plugin +mike diff --git a/docs/.bundle/config b/docs/.bundle/config deleted file mode 100644 index 236922881..000000000 --- a/docs/.bundle/config +++ /dev/null @@ -1,2 +0,0 @@ ---- -BUNDLE_PATH: "vendor/bundle" diff --git a/docs/.gitignore b/docs/.gitignore deleted file mode 100644 index ba9be90d9..000000000 --- a/docs/.gitignore +++ /dev/null @@ -1,3 +0,0 @@ -/vendor -_site -.sass-cache \ No newline at end of file diff --git a/docs/Gemfile b/docs/Gemfile deleted file mode 100644 index a1b0226ed..000000000 --- a/docs/Gemfile +++ /dev/null @@ -1,12 +0,0 @@ -# frozen_string_literal: true - -source "https://rubygems.org" - -git_source(:github) { |repo_name| "https://github.com/#{repo_name}" } - -group :jekyll_plugins do - gem "github-pages" - gem "jekyll-multiple-languages-plugin" - gem "html-proofer" - gem "webrick" -end diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock deleted file mode 100644 index 06ba95df4..000000000 --- a/docs/Gemfile.lock +++ /dev/null @@ -1,290 +0,0 @@ -GEM - remote: https://rubygems.org/ - specs: - activesupport (7.1.3) - base64 - bigdecimal - concurrent-ruby (~> 1.0, >= 1.0.2) - connection_pool (>= 2.2.5) - drb - i18n (>= 1.6, < 2) - minitest (>= 5.1) - mutex_m - tzinfo (~> 2.0) - addressable (2.8.6) - public_suffix (>= 2.0.2, < 6.0) - base64 (0.2.0) - bigdecimal (3.1.6) - coffee-script (2.4.1) - coffee-script-source - execjs - coffee-script-source (1.11.1) - colorator (1.1.0) - commonmarker (0.23.10) - concurrent-ruby (1.2.3) - connection_pool (2.4.1) - dnsruby (1.70.0) - simpleidn (~> 0.2.1) - drb (2.2.0) - ruby2_keywords - em-websocket (0.5.3) - eventmachine (>= 0.12.9) - http_parser.rb (~> 0) - ethon (0.16.0) - ffi (>= 1.15.0) - eventmachine (1.2.7) - execjs (2.9.1) - faraday (2.8.1) - base64 - faraday-net_http (>= 2.0, < 3.1) - ruby2_keywords (>= 0.0.4) - faraday-net_http (3.0.2) - ffi (1.16.3) - forwardable-extended (2.6.0) - gemoji (3.0.1) - github-pages (228) - github-pages-health-check (= 1.17.9) - jekyll (= 3.9.3) - jekyll-avatar (= 0.7.0) - jekyll-coffeescript (= 1.1.1) - jekyll-commonmark-ghpages (= 0.4.0) - jekyll-default-layout (= 0.1.4) - jekyll-feed (= 0.15.1) - jekyll-gist (= 1.5.0) - jekyll-github-metadata (= 2.13.0) - jekyll-include-cache (= 0.2.1) - jekyll-mentions (= 1.6.0) - jekyll-optional-front-matter (= 0.3.2) - jekyll-paginate (= 1.1.0) - jekyll-readme-index (= 0.3.0) - jekyll-redirect-from (= 0.16.0) - jekyll-relative-links (= 0.6.1) - jekyll-remote-theme (= 0.4.3) - jekyll-sass-converter (= 1.5.2) - jekyll-seo-tag (= 2.8.0) - jekyll-sitemap (= 1.4.0) - jekyll-swiss (= 1.0.0) - jekyll-theme-architect (= 0.2.0) - jekyll-theme-cayman (= 0.2.0) - jekyll-theme-dinky (= 0.2.0) - jekyll-theme-hacker (= 0.2.0) - jekyll-theme-leap-day (= 0.2.0) - jekyll-theme-merlot (= 0.2.0) - jekyll-theme-midnight (= 0.2.0) - jekyll-theme-minimal (= 0.2.0) - jekyll-theme-modernist (= 0.2.0) - jekyll-theme-primer (= 0.6.0) - jekyll-theme-slate (= 0.2.0) - jekyll-theme-tactile (= 0.2.0) - jekyll-theme-time-machine (= 0.2.0) - jekyll-titles-from-headings (= 0.5.3) - jemoji (= 0.12.0) - kramdown (= 2.3.2) - kramdown-parser-gfm (= 1.1.0) - liquid (= 4.0.4) - mercenary (~> 0.3) - minima (= 2.5.1) - nokogiri (>= 1.13.6, < 2.0) - rouge (= 3.26.0) - terminal-table (~> 1.4) - github-pages-health-check (1.17.9) - addressable (~> 2.3) - dnsruby (~> 1.60) - octokit (~> 4.0) - public_suffix (>= 3.0, < 5.0) - typhoeus (~> 1.3) - html-pipeline (2.14.3) - activesupport (>= 2) - nokogiri (>= 1.4) - html-proofer (4.4.3) - addressable (~> 2.3) - mercenary (~> 0.3) - nokogiri (~> 1.13) - parallel (~> 1.10) - rainbow (~> 3.0) - typhoeus (~> 1.3) - yell (~> 2.0) - zeitwerk (~> 2.5) - http_parser.rb (0.8.0) - i18n (1.14.1) - concurrent-ruby (~> 1.0) - jekyll (3.9.3) - addressable (~> 2.4) - colorator (~> 1.0) - em-websocket (~> 0.5) - i18n (>= 0.7, < 2) - jekyll-sass-converter (~> 1.0) - jekyll-watch (~> 2.0) - kramdown (>= 1.17, < 3) - liquid (~> 4.0) - mercenary (~> 0.3.3) - pathutil (~> 0.9) - rouge (>= 1.7, < 4) - safe_yaml (~> 1.0) - jekyll-avatar (0.7.0) - jekyll (>= 3.0, < 5.0) - jekyll-coffeescript (1.1.1) - coffee-script (~> 2.2) - coffee-script-source (~> 1.11.1) - jekyll-commonmark (1.4.0) - commonmarker (~> 0.22) - jekyll-commonmark-ghpages (0.4.0) - commonmarker (~> 0.23.7) - jekyll (~> 3.9.0) - jekyll-commonmark (~> 1.4.0) - rouge (>= 2.0, < 5.0) - jekyll-default-layout (0.1.4) - jekyll (~> 3.0) - jekyll-feed (0.15.1) - jekyll (>= 3.7, < 5.0) - jekyll-gist (1.5.0) - octokit (~> 4.2) - jekyll-github-metadata (2.13.0) - jekyll (>= 3.4, < 5.0) - octokit (~> 4.0, != 4.4.0) - jekyll-include-cache (0.2.1) - jekyll (>= 3.7, < 5.0) - jekyll-mentions (1.6.0) - html-pipeline (~> 2.3) - jekyll (>= 3.7, < 5.0) - jekyll-multiple-languages-plugin (1.8.0) - jekyll (>= 2.0, < 5.0) - jekyll-optional-front-matter (0.3.2) - jekyll (>= 3.0, < 5.0) - jekyll-paginate (1.1.0) - jekyll-readme-index (0.3.0) - jekyll (>= 3.0, < 5.0) - jekyll-redirect-from (0.16.0) - jekyll (>= 3.3, < 5.0) - jekyll-relative-links (0.6.1) - jekyll (>= 3.3, < 5.0) - jekyll-remote-theme (0.4.3) - addressable (~> 2.0) - jekyll (>= 3.5, < 5.0) - jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0) - rubyzip (>= 1.3.0, < 3.0) - jekyll-sass-converter (1.5.2) - sass (~> 3.4) - jekyll-seo-tag (2.8.0) - jekyll (>= 3.8, < 5.0) - jekyll-sitemap (1.4.0) - jekyll (>= 3.7, < 5.0) - jekyll-swiss (1.0.0) - jekyll-theme-architect (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-cayman (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-dinky (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-hacker (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-leap-day (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-merlot (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-midnight (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-minimal (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-modernist (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-primer (0.6.0) - jekyll (> 3.5, < 5.0) - jekyll-github-metadata (~> 2.9) - jekyll-seo-tag (~> 2.0) - jekyll-theme-slate (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-tactile (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-time-machine (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-titles-from-headings (0.5.3) - jekyll (>= 3.3, < 5.0) - jekyll-watch (2.2.1) - listen (~> 3.0) - jemoji (0.12.0) - gemoji (~> 3.0) - html-pipeline (~> 2.2) - jekyll (>= 3.0, < 5.0) - kramdown (2.3.2) - rexml - kramdown-parser-gfm (1.1.0) - kramdown (~> 2.0) - liquid (4.0.4) - listen (3.8.0) - rb-fsevent (~> 0.10, >= 0.10.3) - rb-inotify (~> 0.9, >= 0.9.10) - mercenary (0.3.6) - minima (2.5.1) - jekyll (>= 3.5, < 5.0) - jekyll-feed (~> 0.9) - jekyll-seo-tag (~> 2.1) - minitest (5.21.2) - mutex_m (0.2.0) - nokogiri (1.15.5-arm64-darwin) - racc (~> 1.4) - octokit (4.25.1) - faraday (>= 1, < 3) - sawyer (~> 0.9) - parallel (1.24.0) - pathutil (0.16.2) - forwardable-extended (~> 2.6) - public_suffix (4.0.7) - racc (1.7.3) - rainbow (3.1.1) - rb-fsevent (0.11.2) - rb-inotify (0.10.1) - ffi (~> 1.0) - rexml (3.2.6) - rouge (3.26.0) - ruby2_keywords (0.0.5) - rubyzip (2.3.2) - safe_yaml (1.0.5) - sass (3.7.4) - sass-listen (~> 4.0.0) - sass-listen (4.0.0) - rb-fsevent (~> 0.9, >= 0.9.4) - rb-inotify (~> 0.9, >= 0.9.7) - sawyer (0.9.2) - addressable (>= 2.3.5) - faraday (>= 0.17.3, < 3) - simpleidn (0.2.1) - unf (~> 0.1.4) - terminal-table (1.8.0) - unicode-display_width (~> 1.1, >= 1.1.1) - typhoeus (1.4.1) - ethon (>= 0.9.0) - tzinfo (2.0.6) - concurrent-ruby (~> 1.0) - unf (0.1.4) - unf_ext - unf_ext (0.0.9.1) - unicode-display_width (1.8.0) - webrick (1.8.1) - yell (2.2.2) - zeitwerk (2.6.12) - -PLATFORMS - arm64-darwin-21 - arm64-darwin-22 - -DEPENDENCIES - github-pages - html-proofer - jekyll-multiple-languages-plugin - webrick - -BUNDLED WITH - 2.3.14 diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index 56419c2f6..000000000 --- a/docs/_config.yml +++ /dev/null @@ -1,15 +0,0 @@ -repository: hyperledger/firefly -logo: "images/hyperledger-firefly_color.svg" -title: Hyperledger FireFly Docs -baseurl: /firefly -aux_links: - "GitHub": - - "https://github.com/hyperledger/firefly" - "Wiki": - - "https://wiki.hyperledger.org/display/FIR" - "Discord": - - "https://discord.gg/hyperledger" -color_scheme: firefly -plugins: - - jekyll-multiple-languages-plugin -languages: ["en"] diff --git a/docs/_i18n/en.yml b/docs/_i18n/en.yml deleted file mode 100644 index 501860cc6..000000000 --- a/docs/_i18n/en.yml +++ /dev/null @@ -1,61 +0,0 @@ -langs: - en: English - es: EspaΓ±ol -site: - title: Hyperledger FireFly Docs -pages: - advanced_cli_usage: Advanced CLI Usage - api_post_syntax: API Post Syntax - api_query_syntax: API Query Syntax - api_spec: API Spec - apps: Apps - arbitrum: Arbitrum Testnet - architecture: Architecture - avalanche: Avalanche Testnet - binance_smart_chain: Binance Smartchain Testnet - blockchain_protocols: Blockchain Protocols - blockchain_operation_status: Blockchain Operation Status - broadcast_data: Broadcast data - broadcast_shared_data: Broadcast / Shared Data - chains: Connect to remote blockchains - code_hierarchy: FireFly Code Hierarchy - code_overview: FireFly Code Overview - code_repositories: Code Repositories - configuration_reference: Configuration Reference - connector_framework: Connector Framework - contributors: Contributors - custom_smart_contracts: Work with custom smart contracts - data_security: Data Security - deterministic: Deterministic Compute - digital_assets: Digital Assets - faqs: FAQs - firefly_core: Firefly Core - flows: Flows - getting_started: Getting Started - home: Home - introduction: Introduction - key_features: Key Features - moonbeam_testnet: Moonbeam Testnet - multiparty_features: Multiparty Features - multiparty_flow: Multiparty Process Flow - near: NEAR Testnet - optimism: Optimism Testnet - orchestration_engine: Orchestration Engine - polygon_testnet: Polygon Testnet - private_data_exchange: Private Data Exchange - reference: Reference - remote_fabric_network: Remote Fabric Network - release_notes: Release Notes - security: Security - tls: TLS - tools: Tools - tutorials: Tutorials - understanding_firefly: Understanding FireFly - usage_patterns: Usage Patterns - web3_gateway_features: Web3 Gateway Features - basic_auth: Enable basic auth - fabric_test_network: Fabric-Samples Test Network - xdc_testnet: XDC Testnet - zksync_testnet: zkSync Testnet - rotate_dx_certs: Rotate Data Exchange Certificates - tezos_testnet: Tezos Testnet diff --git a/docs/_i18n/es.yml b/docs/_i18n/es.yml deleted file mode 100644 index 5055a2304..000000000 --- a/docs/_i18n/es.yml +++ /dev/null @@ -1,10 +0,0 @@ -pages: - home: PΓ‘gina principal - architecture: Arquitectura - api_spec: API EspecificaciΓ³n - contributors: Colaboradores - faqs: Preguntas mΓ‘s frecuentes - getting_started: Empezando - reference: Referencia - tutorials: Tutoriales - understanding_firefly: Comprender FireFly diff --git a/docs/_i18n/es/index.md b/docs/_i18n/es/index.md deleted file mode 100644 index fd98c5c0b..000000000 --- a/docs/_i18n/es/index.md +++ /dev/null @@ -1,13 +0,0 @@ -# Hyperledger FireFly - -![Hyperledger FireFly](./images/hyperledger_firefly_social.png) - -Hyperledger FireFly es el primer supernodo de cΓ³digo abierto: una pila completa para que las empresas creen y escalen aplicaciones Web3 seguras. - -La API de FireFly para activos digitales, flujos de datos y transacciones de blockchain hace que sea mucho mΓ‘s rΓ‘pido crear aplicaciones listas para producciΓ³n en cadenas y protocolos populares. - -- [Comprender FireFly](./overview/) -- [Referencia](./reference/) -- [Arquitectura](./architecture/) -- [Colaboradores](./contributors/) -- [API EspecificaciΓ³n](./swagger/swagger.html) diff --git a/docs/_includes/css/custom.scss.liquid b/docs/_includes/css/custom.scss.liquid deleted file mode 100644 index 2ad1576e0..000000000 --- a/docs/_includes/css/custom.scss.liquid +++ /dev/null @@ -1 +0,0 @@ -@import "./custom/custom"; diff --git a/docs/_includes/css/just-the-docs.scss.liquid b/docs/_includes/css/just-the-docs.scss.liquid deleted file mode 100644 index 495cd6dd9..000000000 --- a/docs/_includes/css/just-the-docs.scss.liquid +++ /dev/null @@ -1,7 +0,0 @@ -{% if site.logo %} -$logo: "{{ site.logo | absolute_url }}"; -{% endif %} -@import "./support/support"; -@import "./color_schemes/{{ include.color_scheme }}"; -@import "./modules"; -{% include css/custom.scss.liquid %} diff --git a/docs/_includes/footer_custom.html b/docs/_includes/footer_custom.html deleted file mode 100644 index 64e08c290..000000000 --- a/docs/_includes/footer_custom.html +++ /dev/null @@ -1,3 +0,0 @@ -{%- if site.footer_content -%} -

{{ site.footer_content }}

-{%- endif -%} diff --git a/docs/_includes/head.html b/docs/_includes/head.html deleted file mode 100644 index df7ed4b9d..000000000 --- a/docs/_includes/head.html +++ /dev/null @@ -1,42 +0,0 @@ - - - - - {% unless site.plugins contains "jekyll-seo-tag" %} - {% if page.layout == "i18n_page" %}{% t page.title %}{% else %}{{ page.title }}{% endif %} - {% t "site.title" %} - - {% if page.description %} - - {% endif %} - {% endunless %} - - - - - - {% if site.ga_tracking != nil %} - - - - {% endif %} - - {% if site.search_enabled != false %} - - {% endif %} - - - - - - - {% seo %} - - {% include head_custom.html %} - - diff --git a/docs/_includes/header_custom.html b/docs/_includes/header_custom.html deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/_includes/js/custom.js b/docs/_includes/js/custom.js deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/_includes/nav.html b/docs/_includes/nav.html deleted file mode 100644 index bb379914a..000000000 --- a/docs/_includes/nav.html +++ /dev/null @@ -1,99 +0,0 @@ -
    - {%- assign titled_pages = include.pages - | where_exp:"item", "item.title != nil" -%} - - {%- comment -%} - The values of `title` and `nav_order` can be numbers or strings. - Jekyll gives build failures when sorting on mixtures of different types, - so numbers and strings need to be sorted separately. - - Here, numbers are sorted by their values, and come before all strings. - An omitted `nav_order` value is equivalent to the page's `title` value - (except that a numerical `title` value is treated as a string). - - The case-sensitivity of string sorting is determined by `site.nav_sort`. - {%- endcomment -%} - - {%- assign string_ordered_pages = titled_pages - | where_exp:"item", "item.nav_order == nil" -%} - {%- assign nav_ordered_pages = titled_pages - | where_exp:"item", "item.nav_order != nil" -%} - - {%- comment -%} - The nav_ordered_pages have to be added to number_ordered_pages and - string_ordered_pages, depending on the nav_order value. - The first character of the jsonify result is `"` only for strings. - {%- endcomment -%} - {%- assign nav_ordered_groups = nav_ordered_pages - | group_by_exp:"item", "item.nav_order | jsonify | slice: 0" -%} - {%- assign number_ordered_pages = "" | split:"X" -%} - {%- for group in nav_ordered_groups -%} - {%- if group.name == '"' -%} - {%- assign string_ordered_pages = string_ordered_pages | concat: group.items -%} - {%- else -%} - {%- assign number_ordered_pages = number_ordered_pages | concat: group.items -%} - {%- endif -%} - {%- endfor -%} - - {%- assign sorted_number_ordered_pages = number_ordered_pages | sort:"nav_order" -%} - - {%- comment -%} - The string_ordered_pages have to be sorted by nav_order, and otherwise title - (where appending the empty string to a numeric title converts it to a string). - After grouping them by those values, the groups are sorted, then the items - of each group are concatenated. - {%- endcomment -%} - {%- assign string_ordered_groups = string_ordered_pages - | group_by_exp:"item", "item.nav_order | default: item.title | append:''" -%} - {%- if site.nav_sort == 'case_insensitive' -%} - {%- assign sorted_string_ordered_groups = string_ordered_groups | sort_natural:"name" -%} - {%- else -%} - {%- assign sorted_string_ordered_groups = string_ordered_groups | sort:"name" -%} - {%- endif -%} - {%- assign sorted_string_ordered_pages = "" | split:"X" -%} - {%- for group in sorted_string_ordered_groups -%} - {%- assign sorted_string_ordered_pages = sorted_string_ordered_pages | concat: group.items -%} - {%- endfor -%} - - {%- assign pages_list = sorted_number_ordered_pages | concat: sorted_string_ordered_pages -%} - - {%- for node in pages_list -%} - {%- if node.parent == nil -%} - {%- unless node.nav_exclude -%} -
  • - {%- if node.has_children -%} - - {%- endif -%} - {% if node.layout == "i18n_page" %}{% t node.title %}{% else %}{{ node.title }}{% endif %} - {%- if node.has_children -%} - {%- assign children_list = pages_list | where: "parent", node.title -%} - - {%- endif -%} -
    • - {%- endunless -%} - {%- endif -%} - {%- endfor -%} -
diff --git a/docs/_includes/title.html b/docs/_includes/title.html deleted file mode 100644 index 8bd3fa83d..000000000 --- a/docs/_includes/title.html +++ /dev/null @@ -1,5 +0,0 @@ -{% if site.logo %} - -{% else %} - {{ site.title }} -{% endif %} diff --git a/docs/_includes/vendor/anchor_headings.html b/docs/_includes/vendor/anchor_headings.html deleted file mode 100755 index e9ca8626c..000000000 --- a/docs/_includes/vendor/anchor_headings.html +++ /dev/null @@ -1,144 +0,0 @@ -{% capture headingsWorkspace %} - {% comment %} - Copyright (c) 2018 Vladimir "allejo" Jimenez - - Permission is hereby granted, free of charge, to any person - obtaining a copy of this software and associated documentation - files (the "Software"), to deal in the Software without - restriction, including without limitation the rights to use, - copy, modify, merge, publish, distribute, sublicense, and/or sell - copies of the Software, and to permit persons to whom the - Software is furnished to do so, subject to the following - conditions: - - The above copyright notice and this permission notice shall be - included in all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES - OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT - HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, - WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING - FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR - OTHER DEALINGS IN THE SOFTWARE. - {% endcomment %} - {% comment %} - Version 1.0.7 - https://github.com/allejo/jekyll-anchor-headings - - "Be the pull request you wish to see in the world." ~Ben Balter - - Usage: - {% include anchor_headings.html html=content anchorBody="#" %} - - Parameters: - * html (string) - the HTML of compiled markdown generated by kramdown in Jekyll - - Optional Parameters: - * beforeHeading (bool) : false - Set to true if the anchor should be placed _before_ the heading's content - * anchorAttrs (string) : '' - Any custom HTML attributes that will be added to the `` tag; you may NOT use `href`, `class` or `title`; - the `%heading%` and `%html_id%` placeholders are available - * anchorBody (string) : '' - The content that will be placed inside the anchor; the `%heading%` placeholder is available - * anchorClass (string) : '' - The class(es) that will be used for each anchor. Separate multiple classes with a space - * anchorTitle (string) : '' - The `title` attribute that will be used for anchors - * h_min (int) : 1 - The minimum header level to build an anchor for; any header lower than this value will be ignored - * h_max (int) : 6 - The maximum header level to build an anchor for; any header greater than this value will be ignored - * bodyPrefix (string) : '' - Anything that should be inserted inside of the heading tag _before_ its anchor and content - * bodySuffix (string) : '' - Anything that should be inserted inside of the heading tag _after_ its anchor and content - - Output: - The original HTML with the addition of anchors inside of all of the h1-h6 headings. - {% endcomment %} - - {% assign minHeader = include.h_min | default: 1 %} - {% assign maxHeader = include.h_max | default: 6 %} - {% assign beforeHeading = include.beforeHeading %} - {% assign nodes = include.html | split: ' - {% if headerLevel == 0 %} - - {% assign firstChunk = node | split: '>' | first %} - - - {% unless firstChunk contains '<' %} - {% capture node %}{% endcapture %} - {% assign _workspace = node | split: _closingTag %} - {% assign _idWorkspace = _workspace[0] | split: 'id="' %} - {% assign _idWorkspace = _idWorkspace[1] | split: '"' %} - {% assign html_id = _idWorkspace[0] %} - - {% capture _hAttrToStrip %}{{ _workspace[0] | split: '>' | first }}>{% endcapture %} - {% assign header = _workspace[0] | replace: _hAttrToStrip, '' %} - - - {% capture anchor %}{% endcapture %} - - {% if html_id and headerLevel >= minHeader and headerLevel <= maxHeader %} - {% capture anchor %}href="#{{ html_id }}"{% endcapture %} - - {% if include.anchorClass %} - {% capture anchor %}{{ anchor }} class="{{ include.anchorClass }}"{% endcapture %} - {% endif %} - - {% if include.anchorTitle %} - {% capture anchor %}{{ anchor }} title="{{ include.anchorTitle | replace: '%heading%', header }}"{% endcapture %} - {% endif %} - - {% if include.anchorAttrs %} - {% capture anchor %}{{ anchor }} {{ include.anchorAttrs | replace: '%heading%', header | replace: '%html_id%', html_id }}{% endcapture %} - {% endif %} - - {% capture anchor %}{{ include.anchorBody | replace: '%heading%', header | default: '' }}{% endcapture %} - - - {% if beforeHeading %} - {% capture anchor %}{{ anchor }} {% endcapture %} - {% else %} - {% capture anchor %} {{ anchor }}{% endcapture %} - {% endif %} - {% endif %} - - {% capture new_heading %} - - {% endcapture %} - - - {% assign chunkCount = _workspace | size %} - {% if chunkCount > 1 %} - {% capture new_heading %}{{ new_heading }}{{ _workspace | last }}{% endcapture %} - {% endif %} - - {% capture edited_headings %}{{ edited_headings }}{{ new_heading }}{% endcapture %} - {% endfor %} -{% endcapture %}{% assign headingsWorkspace = '' %}{{ edited_headings | strip }} diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html deleted file mode 100644 index 5da3bcebc..000000000 --- a/docs/_layouts/default.html +++ /dev/null @@ -1,238 +0,0 @@ ---- -layout: table_wrappers ---- - - - - -{% include head.html %} - - - - Link - - - - - - Search - - - - - - Menu - - - - - - Expand - - - - - - Document - - - - - - -
-
- {% include title.html %} - - - -
- -
- This site uses Just the Docs, a documentation theme for Jekyll. -
-
-
-
- {% if site.search_enabled != false %} -
-
- - -
-
-
- {% endif %} - {% include header_custom.html %} - {% if site.aux_links %} - - {% endif %} -
-
- {% unless page.url == "/" %} - {% if page.parent %} - {%- for node in pages_list -%} - {%- if node.parent == nil -%} - {%- if page.parent == node.title or page.grand_parent == node.title -%} - {%- assign first_level_url = node.url | absolute_url -%} - {%- endif -%} - {%- if node.has_children -%} - {%- assign children_list = pages_list | where: "parent", node.title -%} - {%- for child in children_list -%} - {%- if page.url == child.url or page.parent == child.title -%} - {%- assign second_level_url = child.url | absolute_url -%} - {%- endif -%} - {%- endfor -%} - {%- endif -%} - {%- endif -%} - {%- endfor -%} - - {% endif %} - {% endunless %} -
- {% if site.heading_anchors != false %} - {% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="" anchorClass="anchor-heading" anchorAttrs="aria-labelledby=\"%html_id%\"" %} - {% else %} - {{ content }} - {% endif %} - - {% if page.has_children == true and page.has_toc != false %} -
-

Table of contents

- - {% endif %} - - {% capture footer_custom %} - {%- include footer_custom.html -%} - {% endcapture %} - {% if footer_custom != "" or site.last_edit_timestamp or site.gh_edit_link %} -
-
- {% if site.back_to_top %} -

{{ site.back_to_top_text }}

- {% endif %} - - {{ footer_custom }} - - {% if site.last_edit_timestamp or site.gh_edit_link %} -
- {% if site.last_edit_timestamp and site.last_edit_time_format and page.last_modified_date %} -

- Page last modified: {{ page.last_modified_date | date: site.last_edit_time_format }}. -

- {% endif %} - {% if - site.gh_edit_link and - site.gh_edit_link_text and - site.gh_edit_repository and - site.gh_edit_branch and - site.gh_edit_view_mode - %} -

- {{ site.gh_edit_link_text }} -

- {% endif %} -
- {% endif %} -
- {% endif %} - -
-
- - {% if site.search_enabled != false %} - {% if site.search.button %} - - - - {% endif %} - -
- {% endif %} -
- - - diff --git a/docs/_layouts/i18n_page.html b/docs/_layouts/i18n_page.html deleted file mode 100644 index 5e7112684..000000000 --- a/docs/_layouts/i18n_page.html +++ /dev/null @@ -1,5 +0,0 @@ ---- -layout: default ---- - -{{ content }} diff --git a/docs/_layouts/page.html b/docs/_layouts/page.html deleted file mode 100644 index 5e7112684..000000000 --- a/docs/_layouts/page.html +++ /dev/null @@ -1,5 +0,0 @@ ---- -layout: default ---- - -{{ content }} diff --git a/docs/_sass/base.scss b/docs/_sass/base.scss deleted file mode 100644 index c3b669872..000000000 --- a/docs/_sass/base.scss +++ /dev/null @@ -1,108 +0,0 @@ -// -// Base element style overrides -// -// stylelint-disable selector-no-type, selector-max-type - -* { - box-sizing: border-box; -} - -::selection { - color: $white; - background: $link-color; -} - -html { - @include fs-4; - scroll-behavior: smooth; -} - -body { - font-family: $body-font-family; - font-size: inherit; - line-height: $body-line-height; - color: $body-text-color; - background-color: $body-background-color; -} - -ol, -ul, -dl, -pre, -address, -blockquote, -table, -div, -hr, -form, -fieldset, -noscript .table-wrapper { - margin-top: 0; -} - -h1, -h2, -h3, -h4, -h5, -h6 { - margin-top: 0; - margin-bottom: 1em; - font-weight: 500; - line-height: $body-heading-line-height; - color: $body-heading-color; -} - -p { - margin-top: 1em; - margin-bottom: 1em; -} - -a { - color: $link-color; - text-decoration: none; -} - -a:not([class]) { - text-decoration: none; - background-image: linear-gradient($border-color 0%, $border-color 100%); - background-repeat: repeat-x; - background-position: 0 100%; - background-size: 1px 1px; - - &:hover { - background-image: linear-gradient( - rgba($link-color, 0.45) 0%, - rgba($link-color, 0.45) 100% - ); - background-size: 1px 1px; - } -} - -code { - font-family: $mono-font-family; - font-size: 0.75em; - line-height: $body-line-height; -} - -figure, -pre { - margin: 0; -} - -li { - margin: 0.25em 0; -} - -img { - max-width: 100%; - height: auto; -} - -hr { - height: 1px; - padding: 0; - margin: $sp-6 0; - background-color: $border-color; - border: 0; -} diff --git a/docs/_sass/buttons.scss b/docs/_sass/buttons.scss deleted file mode 100644 index 57660e05c..000000000 --- a/docs/_sass/buttons.scss +++ /dev/null @@ -1,118 +0,0 @@ -// -// Buttons and things that look like buttons -// -// stylelint-disable color-named - -.btn { - display: inline-block; - box-sizing: border-box; - padding-top: 0.3em; - padding-right: 1em; - padding-bottom: 0.3em; - padding-left: 1em; - margin: 0; - font-family: inherit; - font-size: inherit; - font-weight: 500; - line-height: 1.5; - color: $link-color; - text-decoration: none; - vertical-align: baseline; - cursor: pointer; - background-color: $base-button-color; - border-width: 0; - border-radius: $border-radius; - box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); - appearance: none; - - &:focus { - text-decoration: none; - outline: none; - box-shadow: 0 0 0 3px rgba(blue, 0.25); - } - - &:focus:hover, - &.selected:focus { - box-shadow: 0 0 0 3px rgba(blue, 0.25); - } - - &:hover, - &.zeroclipboard-is-hover { - color: darken($link-color, 2%); - } - - &:hover, - &:active, - &.zeroclipboard-is-hover, - &.zeroclipboard-is-active { - text-decoration: none; - background-color: darken($base-button-color, 1%); - } - - &:active, - &.selected, - &.zeroclipboard-is-active { - background-color: darken($base-button-color, 3%); - background-image: none; - box-shadow: inset 0 2px 4px rgba(0, 0, 0, 0.15); - } - - &.selected:hover { - background-color: darken(#dcdcdc, 5%); - } - - &:disabled, - &.disabled { - &, - &:hover { - color: rgba(102, 102, 102, 0.5); - cursor: default; - background-color: rgba(229, 229, 229, 0.5); - background-image: none; - box-shadow: none; - } - } -} - -.btn-outline { - color: $link-color; - background: transparent; - box-shadow: inset 0 0 0 2px $grey-lt-300; - - &:hover, - &:active, - &.zeroclipboard-is-hover, - &.zeroclipboard-is-active { - color: darken($link-color, 4%); - text-decoration: none; - background-color: transparent; - box-shadow: inset 0 0 0 3px $grey-lt-300; - } - - &:focus { - text-decoration: none; - outline: none; - box-shadow: inset 0 0 0 2px $grey-dk-100, 0 0 0 3px rgba(blue, 0.25); - } - - &:focus:hover, - &.selected:focus { - box-shadow: inset 0 0 0 2px $grey-dk-100; - } -} - -.btn-primary { - @include btn-color($white, $btn-primary-color); -} - -.btn-purple { - @include btn-color($white, $purple-100); -} - -.btn-blue { - @include btn-color($white, $blue-000); -} - -.btn-green { - @include btn-color($white, $green-100); -} diff --git a/docs/_sass/code.scss b/docs/_sass/code.scss deleted file mode 100644 index f03891290..000000000 --- a/docs/_sass/code.scss +++ /dev/null @@ -1,340 +0,0 @@ -// -// Code and syntax highlighting -// -// stylelint-disable selector-no-qualifying-type, declaration-block-semicolon-newline-after,declaration-block-single-line-max-declarations, selector-no-type, selector-max-type - -code { - padding: 0.2em 0.15em; - font-weight: 400; - background-color: $code-background-color; - border: $border $border-color; - border-radius: $border-radius; -} - -// Avoid appearance of dark border around visited code links in Safari -a:visited code { - border-color: $border-color; -} - -// Content structure for highlighted code blocks using fences or Liquid -// -// ```[LANG]...```, no kramdown line_numbers: -// div.[language-LANG.]highlighter-rouge > div.highlight > pre.highlight > code -// -// ```[LANG]...```, kramdown line_numbers = true: -// div.[language-LANG.]highlighter-rouge > div.highlight > pre.highlight > code -// > div.table-wrapper > table.rouge-table > tbody > tr -// > td.rouge-gutter.gl > pre.lineno -// | td.rouge-code > pre -// -// {% highlight LANG %}...{% endhighlight %}: -// figure.highlight > pre > code.language-LANG -// -// {% highlight LANG linenos %}...{% endhighlight %}: -// figure.highlight > pre > code.language-LANG -// > div.table-wrapper > table.rouge-table > tbody > tr -// > td.gutter.gl > pre.lineno -// | td.code > pre -// -// fix_linenos removes the outermost pre when it encloses table.rouge-table -// -// See docs/index-test.md for some tests. -// -// No kramdown line_numbers: fences and Liquid highlighting look the same. -// Kramdown line_numbers = true: fences have a wider gutter than with Liquid? - -// ```[LANG]...``` -div.highlighter-rouge { - padding: $sp-3; - margin-top: 0; - margin-bottom: $sp-3; - overflow-x: auto; - background-color: $code-background-color; - border-radius: $border-radius; - box-shadow: none; - -webkit-overflow-scrolling: touch; - - div.highlight, - pre.highlight, - code { - padding: 0; - margin: 0; - border: 0; - } -} - -// {% highlight LANG %}...{% endhighlight %}, -// {% highlight LANG linenos %}...{% endhighlight %}: -figure.highlight { - padding: $sp-3; - margin-top: 0; - margin-bottom: $sp-3; - background-color: $code-background-color; - border-radius: $border-radius; - box-shadow: none; - -webkit-overflow-scrolling: touch; - - pre, - code { - padding: 0; - margin: 0; - border: 0; - } -} - -// ```[LANG]...```, kramdown line_numbers = true, -// {% highlight LANG linenos %}...{% endhighlight %}: -.highlight .table-wrapper { - padding: 0; - margin: 0; - border: 0; - box-shadow: none; - - td, - pre { - @include fs-2; - min-width: 0; - padding: 0; - background-color: $code-background-color; - border: 0; - } - - td.gl { - padding-right: $sp-3; - } - - pre { - margin: 0; - line-height: 2; - } -} - -.highlight .c { - color: #586e75; -} // comment // -.highlight .err { - color: #93a1a1; -} // error // -.highlight .g { - color: #93a1a1; -} // generic // -.highlight .k { - color: #859900; -} // keyword // -.highlight .l { - color: #93a1a1; -} // literal // -.highlight .n { - color: #93a1a1; -} // name // -.highlight .o { - color: #859900; -} // operator // -.highlight .x { - color: #cb4b16; -} // other // -.highlight .p { - color: #93a1a1; -} // punctuation // -.highlight .cm { - color: #586e75; -} // comment.multiline // -.highlight .cp { - color: #859900; -} // comment.preproc // -.highlight .c1 { - color: #586e75; -} // comment.single // -.highlight .cs { - color: #859900; -} // comment.special // -.highlight .gd { - color: #2aa198; -} // generic.deleted // -.highlight .ge { - font-style: italic; - color: #93a1a1; -} // generic.emph // -.highlight .gr { - color: #dc322f; -} // generic.error // -.highlight .gh { - color: #cb4b16; -} // generic.heading // -.highlight .gi { - color: #859900; -} // generic.inserted // -.highlight .go { - color: #93a1a1; -} // generic.output // -.highlight .gp { - color: #93a1a1; -} // generic.prompt // -.highlight .gs { - font-weight: bold; - color: #93a1a1; -} // generic.strong // -.highlight .gu { - color: #cb4b16; -} // generic.subheading // -.highlight .gt { - color: #93a1a1; -} // generic.traceback // -.highlight .kc { - color: #cb4b16; -} // keyword.constant // -.highlight .kd { - color: #268bd2; -} // keyword.declaration // -.highlight .kn { - color: #859900; -} // keyword.namespace // -.highlight .kp { - color: #859900; -} // keyword.pseudo // -.highlight .kr { - color: #268bd2; -} // keyword.reserved // -.highlight .kt { - color: #dc322f; -} // keyword.type // -.highlight .ld { - color: #93a1a1; -} // literal.date // -.highlight .m { - color: #2aa198; -} // literal.number // -.highlight .s { - color: #2aa198; -} // literal.string // -.highlight .na { - color: #555; -} // name.attribute // -.highlight .nb { - color: #b58900; -} // name.builtin // -.highlight .nc { - color: #268bd2; -} // name.class // -.highlight .no { - color: #cb4b16; -} // name.constant // -.highlight .nd { - color: #268bd2; -} // name.decorator // -.highlight .ni { - color: #cb4b16; -} // name.entity // -.highlight .ne { - color: #cb4b16; -} // name.exception // -.highlight .nf { - color: #268bd2; -} // name.function // -.highlight .nl { - color: #555; -} // name.label // -.highlight .nn { - color: #93a1a1; -} // name.namespace // -.highlight .nx { - color: #555; -} // name.other // -.highlight .py { - color: #93a1a1; -} // name.property // -.highlight .nt { - color: #268bd2; -} // name.tag // -.highlight .nv { - color: #268bd2; -} // name.variable // -.highlight .ow { - color: #859900; -} // operator.word // -.highlight .w { - color: #93a1a1; -} // text.whitespace // -.highlight .mf { - color: #2aa198; -} // literal.number.float // -.highlight .mh { - color: #2aa198; -} // literal.number.hex // -.highlight .mi { - color: #2aa198; -} // literal.number.integer // -.highlight .mo { - color: #2aa198; -} // literal.number.oct // -.highlight .sb { - color: #586e75; -} // literal.string.backtick // -.highlight .sc { - color: #2aa198; -} // literal.string.char // -.highlight .sd { - color: #93a1a1; -} // literal.string.doc // -.highlight .s2 { - color: #2aa198; -} // literal.string.double // -.highlight .se { - color: #cb4b16; -} // literal.string.escape // -.highlight .sh { - color: #93a1a1; -} // literal.string.heredoc // -.highlight .si { - color: #2aa198; -} // literal.string.interpol // -.highlight .sx { - color: #2aa198; -} // literal.string.other // -.highlight .sr { - color: #dc322f; -} // literal.string.regex // -.highlight .s1 { - color: #2aa198; -} // literal.string.single // -.highlight .ss { - color: #2aa198; -} // literal.string.symbol // -.highlight .bp { - color: #268bd2; -} // name.builtin.pseudo // -.highlight .vc { - color: #268bd2; -} // name.variable.class // -.highlight .vg { - color: #268bd2; -} // name.variable.global // -.highlight .vi { - color: #268bd2; -} // name.variable.instance // -.highlight .il { - color: #2aa198; -} // literal.number.integer.long // - -// -// Code examples (rendered) -// - -.code-example { - padding: $sp-3; - margin-bottom: $sp-3; - overflow: auto; - border: 1px solid $border-color; - border-radius: $border-radius; - - + .highlighter-rouge, - + figure.highlight { - position: relative; - margin-top: -$sp-4; - border-right: 1px solid $border-color; - border-bottom: 1px solid $border-color; - border-left: 1px solid $border-color; - border-top-left-radius: 0; - border-top-right-radius: 0; - } -} diff --git a/docs/_sass/color_schemes/dark.scss b/docs/_sass/color_schemes/dark.scss deleted file mode 100644 index a25f449c6..000000000 --- a/docs/_sass/color_schemes/dark.scss +++ /dev/null @@ -1,17 +0,0 @@ -$body-background-color: $grey-dk-300; -$sidebar-color: $grey-dk-300; -$border-color: $grey-dk-200; - -$body-text-color: $grey-lt-300; -$body-heading-color: $grey-lt-000; -$nav-child-link-color: $grey-dk-000; -$search-result-preview-color: $grey-dk-000; - -$link-color: $blue-000; -$btn-primary-color: $blue-200; -$base-button-color: $grey-dk-250; - -$code-background-color: $grey-dk-250; -$search-background-color: $grey-dk-250; -$table-background-color: $grey-dk-250; -$feedback-color: darken($sidebar-color, 3%); diff --git a/docs/_sass/color_schemes/firefly.scss b/docs/_sass/color_schemes/firefly.scss deleted file mode 100644 index 0871fc1c9..000000000 --- a/docs/_sass/color_schemes/firefly.scss +++ /dev/null @@ -1,168 +0,0 @@ -// -// Typography -// - -$body-font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", - Roboto, "Helvetica Neue", Arial, sans-serif !default; -$mono-font-family: "SFMono-Regular", Menlo, Consolas, Monospace !default; -$root-font-size: 16px !default; // Base font-size for rems -$body-line-height: 1.4 !default; -$content-line-height: 1.6 !default; -$body-heading-line-height: 1.25 !default; - -// -// Font size -// `-sm` suffix is the size at the small (and above) media query -// - -$font-size-1: 9px !default; -$font-size-1-sm: 10px !default; -$font-size-2: 11px !default; //h4 - uppercased!, h6 not uppercased, text-small -$font-size-3: 12px !default; //h5 -$font-size-4: 14px !default; -$font-size-5: 16px !default; //h3 -$font-size-6: 18px !default; //h2 -$font-size-7: 24px !default; -$font-size-8: 32px !default; //h1 -$font-size-9: 36px !default; -$font-size-10: 42px !default; -$font-size-10-sm: 48px !default; - -// -// Colors -// - -$white: #fff !default; - -$grey-dk-000: #959396 !default; -$grey-dk-100: #5c5962 !default; -$grey-dk-200: #44434d !default; -$grey-dk-250: #302d36 !default; -$grey-dk-300: #27262b !default; - -$grey-lt-000: #f5f6fa !default; -$grey-lt-100: #eeebee !default; -$grey-lt-200: #ecebed !default; -$grey-lt-300: #e6e1e8 !default; - -$purple-000: #7253ed !default; -$purple-100: #5e41d0 !default; -$purple-200: #4e26af !default; -$purple-300: #381885 !default; - -$blue-000: #2c84fa !default; -$blue-100: #2869e6 !default; -$blue-200: #264caf !default; -$blue-300: #183385 !default; - -$green-000: #41d693 !default; -$green-100: #11b584 !default; -$green-200: #009c7b !default; -$green-300: #026e57 !default; - -$yellow-000: #ffeb82 !default; -$yellow-100: #fadf50 !default; -$yellow-200: #f7d12e !default; -$yellow-300: #e7af06 !default; - -$red-000: #f77e7e !default; -$red-100: #f96e65 !default; -$red-200: #e94c4c !default; -$red-300: #dd2e2e !default; - -$firefly-orange: #ff8a00 !default; -$firefly-pink: #cc01ab !default; -$firefly-purple: #6b00f2 !default; -$firefly-red: #e1111e !default; -$firefly-yellow: #ffca00 !default; - -$body-background-color: $white !default; -$sidebar-color: $grey-lt-000 !default; -$search-background-color: $white !default; -$table-background-color: $white !default; -$code-background-color: $grey-lt-000 !default; -$feedback-color: darken($sidebar-color, 3%) !default; - -$body-text-color: $grey-dk-100 !default; -$body-heading-color: $grey-dk-300 !default; -$search-result-preview-color: $grey-dk-000 !default; -$nav-child-link-color: $grey-dk-100 !default; -$link-color: $firefly-purple; -$btn-primary-color: $firefly-purple; -$base-button-color: #f7f7f7 !default; - -// -// Spacing -// - -$spacing-unit: 1rem; // 1rem == 16px - -$spacers: ( - sp-0: 0, - sp-1: $spacing-unit * 0.25, - sp-2: $spacing-unit * 0.5, - sp-3: $spacing-unit * 0.75, - sp-4: $spacing-unit, - sp-5: $spacing-unit * 1.5, - sp-6: $spacing-unit * 2, - sp-7: $spacing-unit * 2.5, - sp-8: $spacing-unit * 3, - sp-9: $spacing-unit * 3.5, - sp-10: $spacing-unit * 4, -) !default; - -$sp-1: map-get($spacers, sp-1) !default; // 0.25 rem == 4px -$sp-2: map-get($spacers, sp-2) !default; // 0.5 rem == 8px -$sp-3: map-get($spacers, sp-3) !default; // 0.75 rem == 12px -$sp-4: map-get($spacers, sp-4) !default; // 1 rem == 16px -$sp-5: map-get($spacers, sp-5) !default; // 1.5 rem == 24px -$sp-6: map-get($spacers, sp-6) !default; // 2 rem == 32px -$sp-7: map-get($spacers, sp-7) !default; // 2.5 rem == 40px -$sp-8: map-get($spacers, sp-8) !default; // 3 rem == 48px -$sp-9: map-get($spacers, sp-9) !default; // 3.5 rem == 56px -$sp-10: map-get($spacers, sp-10) !default; // 4 rem == 64px - -// -// Borders -// - -$border: 1px solid !default; -$border-radius: 4px !default; -$border-color: $grey-lt-100 !default; - -// -// Grid system -// - -$gutter-spacing: $sp-6 !default; -$gutter-spacing-sm: $sp-4 !default; -$nav-width: 264px !default; -$nav-width-md: 248px !default; -$nav-list-item-height: $sp-6 !default; -$nav-list-item-height-sm: $sp-8 !default; -$nav-list-expander-right: true; -$content-width: 800px !default; -$header-height: 60px !default; -$search-results-width: $content-width - $nav-width !default; -$transition-duration: 400ms; - -// -// Media queries in pixels -// - -$media-queries: ( - xs: 320px, - sm: 500px, - md: $content-width, - lg: $content-width + $nav-width, - xl: 1400px, -) !default; - -blockquote { - background-color: $grey-lt-000; - padding: $sp-1 $sp-5 $sp-1 $sp-5; - border-radius: $border-radius; - border-left: $sp-1 solid $firefly-yellow; - margin-inline-start: $sp-5; - margin-inline-end: $sp-5; -} \ No newline at end of file diff --git a/docs/_sass/color_schemes/light.scss b/docs/_sass/color_schemes/light.scss deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/_sass/content.scss b/docs/_sass/content.scss deleted file mode 100644 index a53271ad8..000000000 --- a/docs/_sass/content.scss +++ /dev/null @@ -1,231 +0,0 @@ -@charset "UTF-8"; - -// -// Styles for rendered markdown in the .main-content container -// -// stylelint-disable selector-no-type, max-nesting-depth, selector-max-compound-selectors, selector-max-type - -.main-content { - line-height: $content-line-height; - - ol, - ul, - dl, - pre, - address, - blockquote, - .table-wrapper { - margin-top: 0.5em; - } - - a { - overflow: hidden; - text-overflow: ellipsis; - white-space: nowrap; - } - - ul, - ol { - padding-left: 1.5em; - } - - li { - .highlight { - margin-top: $sp-1; - } - } - - ol { - list-style-type: none; - counter-reset: step-counter; - - > li { - position: relative; - - &::before { - position: absolute; - top: 0.2em; - left: -1.6em; - color: $grey-dk-000; - content: counter(step-counter); - counter-increment: step-counter; - @include fs-3; - - @include mq(sm) { - top: 0.11em; - } - } - - ol { - counter-reset: sub-counter; - - li { - &::before { - content: counter(sub-counter, lower-alpha); - counter-increment: sub-counter; - } - } - } - } - } - - ul { - list-style: none; - - > li { - &::before { - position: absolute; - margin-left: -1.4em; - color: $grey-dk-000; - content: "β€’"; - } - } - } - - .task-list { - padding-left: 0; - } - - .task-list-item { - display: flex; - align-items: center; - - &::before { - content: ""; - } - } - - .task-list-item-checkbox { - margin-right: 0.6em; - } - - hr + * { - margin-top: 0; - } - - h1:first-of-type { - margin-top: 0.5em; - } - - dl { - display: grid; - grid-template: auto / 10em 1fr; - } - - dt, - dd { - margin: 0.25em 0; - } - - dt { - grid-column: 1; - font-weight: 500; - text-align: right; - &::after { - content: ":"; - } - } - - dd { - grid-column: 2; - margin-bottom: 0; - margin-left: 1em; - blockquote, - div, - dl, - dt, - h1, - h2, - h3, - h4, - h5, - h6, - li, - ol, - p, - pre, - table, - ul, - .table-wrapper { - &:first-child { - margin-top: 0; - } - } - } - - dd, - ol, - ul { - dl:first-child { - dt:first-child, - dd:nth-child(2) { - margin-top: 0; - } - } - } - - .anchor-heading { - position: absolute; - right: -$sp-4; - width: $sp-5; - height: 100%; - padding-right: $sp-1; - padding-left: $sp-1; - overflow: visible; - - @include mq(md) { - right: auto; - left: -$sp-5; - } - - svg { - display: inline-block; - width: 100%; - height: 100%; - color: $link-color; - visibility: hidden; - } - } - - .anchor-heading:hover, - h1:hover > .anchor-heading, - h2:hover > .anchor-heading, - h3:hover > .anchor-heading, - h4:hover > .anchor-heading, - h5:hover > .anchor-heading, - h6:hover > .anchor-heading { - svg { - visibility: visible; - } - } - - summary { - cursor: pointer; - } - - h1, - h2, - h3, - h4, - h5, - h6 { - position: relative; - margin-top: 1.5em; - margin-bottom: 0.25em; - - &:first-child { - margin-top: $sp-2; - } - - + table, - + .table-wrapper, - + .code-example, - + .highlighter-rouge { - margin-top: 1em; - } - - + p { - margin-top: 0; - } - } -} diff --git a/docs/_sass/custom/custom.scss b/docs/_sass/custom/custom.scss deleted file mode 100644 index 225e20f08..000000000 --- a/docs/_sass/custom/custom.scss +++ /dev/null @@ -1,24 +0,0 @@ -.dropdown-content { - display: none; - position: absolute; - background-color: #f9f9f9; - min-width: 160px; - box-shadow: 0px 8px 16px 0px rgba(0,0,0,0.2); - z-index: 1; - padding-left: 0; - list-style-type: none; -} - -.dropdown:hover .dropdown-content { - display: flex; - flex-direction: column; -} - -.dropdown-content a { - flex-grow: 1; - padding: $sp-4; - background: none; -} -.dropdown-content a:hover { - background: $grey-lt-100; -} \ No newline at end of file diff --git a/docs/_sass/labels.scss b/docs/_sass/labels.scss deleted file mode 100644 index e08ae80de..000000000 --- a/docs/_sass/labels.scss +++ /dev/null @@ -1,37 +0,0 @@ -// -// Labels (not the form kind) -// - -.label, -.label-blue { - display: inline-block; - padding-top: 0.16em; - padding-right: 0.56em; - padding-bottom: 0.16em; - padding-left: 0.56em; - margin-right: $sp-2; - margin-left: $sp-2; - color: $white; - text-transform: uppercase; - vertical-align: middle; - background-color: $blue-100; - @include fs-2; - border-radius: 12px; -} - -.label-green { - background-color: $green-200; -} - -.label-purple { - background-color: $purple-100; -} - -.label-red { - background-color: $red-200; -} - -.label-yellow { - color: $grey-dk-200; - background-color: $yellow-200; -} diff --git a/docs/_sass/layout.scss b/docs/_sass/layout.scss deleted file mode 100644 index 004cbe76d..000000000 --- a/docs/_sass/layout.scss +++ /dev/null @@ -1,205 +0,0 @@ -// -// The basic two column layout -// - -.side-bar { - z-index: 0; - display: flex; - flex-wrap: wrap; - background-color: $sidebar-color; - - @include mq(md) { - flex-wrap: nowrap; - position: fixed; - width: $nav-width-md; - height: 100%; - flex-direction: column; - border-right: $border $border-color; - align-items: flex-end; - } - - @include mq(lg) { - width: calc((100% - #{$nav-width + $content-width}) / 2 + #{$nav-width}); - min-width: $nav-width; - } -} - -.main { - @include mq(md) { - position: relative; - max-width: $content-width; - margin-left: $nav-width-md; - } - - @include mq(lg) { - margin-left: calc( - (100% - #{$nav-width + $content-width}) / 2 + #{$nav-width} - ); - } -} - -.main-content-wrap { - @include container; - padding-top: $gutter-spacing-sm; - padding-bottom: $gutter-spacing-sm; - - @include mq(md) { - padding-top: $gutter-spacing; - padding-bottom: $gutter-spacing; - } -} - -.main-header { - z-index: 0; - display: none; - background-color: $sidebar-color; - - @include mq(md) { - display: flex; - justify-content: space-between; - height: $header-height; - background-color: $body-background-color; - border-bottom: $border $border-color; - } - - &.nav-open { - display: block; - - @include mq(md) { - display: flex; - } - } -} - -.site-nav, -.site-header, -.site-footer { - width: 100%; - - @include mq(lg) { - width: $nav-width; - } -} - -.site-nav { - display: none; - - &.nav-open { - display: block; - } - - @include mq(md) { - display: block; - padding-top: $sp-8; - padding-bottom: $gutter-spacing-sm; - overflow-y: auto; - flex: 1 1 auto; - } -} - -.site-header { - display: flex; - min-height: $header-height; - align-items: center; - - @include mq(md) { - height: $header-height; - max-height: $header-height; - border-bottom: $border $border-color; - } -} - -.site-title { - @include container; - flex-grow: 1; - display: flex; - height: 100%; - align-items: center; - padding-top: $sp-3; - padding-bottom: $sp-3; - color: $body-heading-color; - @include fs-6; - - @include mq(md) { - padding-top: $sp-2; - padding-bottom: $sp-2; - } -} - -@if variable-exists(logo) { - .site-logo { - width: 100%; - height: 100%; - background-image: url($logo); - background-repeat: no-repeat; - background-position: left center; - background-size: contain; - } -} - -.site-button { - display: flex; - height: 100%; - padding: $gutter-spacing-sm; - align-items: center; -} - -@include mq(md) { - .site-header .site-button { - display: none; - } -} - -.site-title:hover { - background-image: linear-gradient( - -90deg, - rgba($feedback-color, 1) 0%, - rgba($feedback-color, 0.8) 80%, - rgba($feedback-color, 0) 100% - ); -} - -.site-button:hover { - background-image: linear-gradient( - -90deg, - rgba($feedback-color, 1) 0%, - rgba($feedback-color, 0.8) 100% - ); -} - -// stylelint-disable selector-max-type - -body { - position: relative; - padding-bottom: $sp-10; - overflow-y: scroll; - - @include mq(md) { - position: static; - padding-bottom: 0; - } -} - -// stylelint-enable selector-max-type - -.site-footer { - @include container; - position: absolute; - bottom: 0; - left: 0; - padding-top: $sp-4; - padding-bottom: $sp-4; - color: $grey-dk-000; - @include fs-2; - - @include mq(md) { - position: static; - justify-self: end; - } -} - -.icon { - width: $sp-5; - height: $sp-5; - color: $link-color; -} diff --git a/docs/_sass/modules.scss b/docs/_sass/modules.scss deleted file mode 100644 index d82591b75..000000000 --- a/docs/_sass/modules.scss +++ /dev/null @@ -1,20 +0,0 @@ -// -// Import external dependencies -// -@import "./vendor/normalize.scss/normalize.scss"; - -// -// Modules -// -@import "./base"; -@import "./layout"; -@import "./content"; -@import "./navigation"; -@import "./typography"; -@import "./labels"; -@import "./buttons"; -@import "./search"; -@import "./tables"; -@import "./code"; -@import "./utilities/utilities"; -@import "./print"; diff --git a/docs/_sass/navigation.scss b/docs/_sass/navigation.scss deleted file mode 100644 index 521c15fa1..000000000 --- a/docs/_sass/navigation.scss +++ /dev/null @@ -1,219 +0,0 @@ -// -// Main nav, breadcrumb, etc... -// -// stylelint-disable selector-no-type, max-nesting-depth, selector-max-compound-selectors, selector-max-type, selector-max-specificity - -.nav-list { - padding: 0; - margin-top: 0; - margin-bottom: 0; - list-style: none; - - .nav-list-item { - @include fs-4; - position: relative; - margin: 0; - - @include mq(md) { - @include fs-3; - } - - .nav-list-link { - display: block; - min-height: $nav-list-item-height-sm; - padding-top: $sp-1; - padding-bottom: $sp-1; - line-height: #{$nav-list-item-height-sm - 2 * $sp-1}; - @if $nav-list-expander-right { - padding-right: $nav-list-item-height-sm; - padding-left: $gutter-spacing-sm; - } @else { - padding-right: $gutter-spacing-sm; - padding-left: $nav-list-item-height-sm; - } - - @include mq(md) { - min-height: $nav-list-item-height; - line-height: #{$nav-list-item-height - 2 * $sp-1}; - @if $nav-list-expander-right { - padding-right: $nav-list-item-height; - padding-left: $gutter-spacing; - } @else { - padding-right: $gutter-spacing; - padding-left: $nav-list-item-height; - } - } - - &.active { - font-weight: 600; - text-decoration: none; - } - - &:hover, - &.active { - background-image: linear-gradient( - -90deg, - rgba($feedback-color, 1) 0%, - rgba($feedback-color, 0.8) 80%, - rgba($feedback-color, 0) 100% - ); - } - } - - .nav-list-expander { - position: absolute; - @if $nav-list-expander-right { - right: 0; - } - width: $nav-list-item-height-sm; - height: $nav-list-item-height-sm; - padding-top: #{$nav-list-item-height-sm / 4}; - padding-right: #{$nav-list-item-height-sm / 4}; - padding-bottom: #{$nav-list-item-height-sm / 4}; - padding-left: #{$nav-list-item-height-sm / 4}; - color: $link-color; - - @include mq(md) { - width: $nav-list-item-height; - height: $nav-list-item-height; - padding-top: #{$nav-list-item-height / 4}; - padding-right: #{$nav-list-item-height / 4}; - padding-bottom: #{$nav-list-item-height / 4}; - padding-left: #{$nav-list-item-height / 4}; - } - - &:hover { - background-image: linear-gradient( - -90deg, - rgba($feedback-color, 1) 0%, - rgba($feedback-color, 0.8) 100% - ); - } - - @if $nav-list-expander-right { - svg { - transform: rotate(90deg); - } - } - } - - > .nav-list { - display: none; - padding-left: $sp-3; - list-style: none; - - .nav-list-item { - position: relative; - - .nav-list-link { - color: $nav-child-link-color; - } - - .nav-list-expander { - color: $nav-child-link-color; - } - } - } - - &.active { - > .nav-list-expander svg { - @if $nav-list-expander-right { - transform: rotate(-90deg); - } @else { - transform: rotate(90deg); - } - } - - > .nav-list { - display: block; - } - } - } -} - -.nav-category { - padding-top: $sp-2; - padding-right: $gutter-spacing-sm; - padding-bottom: $sp-2; - padding-left: $gutter-spacing-sm; - font-weight: 600; - text-align: end; - text-transform: uppercase; - border-bottom: $border $border-color; - @include fs-2; - - @include mq(md) { - padding-right: $gutter-spacing; - padding-left: $gutter-spacing; - margin-top: $gutter-spacing-sm; - text-align: start; - - &:first-child { - margin-top: 0; - } - } -} - -// Aux nav - -.aux-nav { - height: 100%; - overflow-x: auto; - @include fs-2; - - .aux-nav-list { - display: flex; - height: 100%; - padding: 0; - margin: 0; - list-style: none; - } - - .aux-nav-list-item { - display: inline-block; - height: 100%; - padding: 0; - margin: 0; - } - - @include mq(md) { - padding-right: $gutter-spacing-sm; - } -} - -// Breadcrumb nav - -.breadcrumb-nav { - @include mq(md) { - margin-top: -$sp-4; - } -} - -.breadcrumb-nav-list { - padding-left: 0; - margin-bottom: $sp-3; - list-style: none; -} - -.breadcrumb-nav-list-item { - display: table-cell; - @include fs-2; - - &::before { - display: none; - } - - &::after { - display: inline-block; - margin-right: $sp-2; - margin-left: $sp-2; - color: $grey-dk-000; - content: "/"; - } - - &:last-child { - &::after { - content: ""; - } - } -} diff --git a/docs/_sass/print.scss b/docs/_sass/print.scss deleted file mode 100644 index 6e6de3734..000000000 --- a/docs/_sass/print.scss +++ /dev/null @@ -1,40 +0,0 @@ -// stylelint-disable selector-max-specificity, selector-max-id, selector-max-type, selector-no-qualifying-type, primer/no-override, - -@media print { - .site-footer, - .site-button, - #edit-this-page, - #back-to-top, - .site-nav, - .main-header { - display: none !important; - } - - .side-bar { - width: 100%; - height: auto; - border-right: 0 !important; - } - - .site-header { - border-bottom: 1px solid $border-color; - } - - .site-title { - font-size: $root-font-size !important; - font-weight: 700 !important; - } - - .text-small { - font-size: 8pt !important; - } - - pre.highlight { - border: 1px solid $border-color; - } - - .main { - max-width: none; - margin-left: 0; - } -} diff --git a/docs/_sass/search.scss b/docs/_sass/search.scss deleted file mode 100644 index 4290210d0..000000000 --- a/docs/_sass/search.scss +++ /dev/null @@ -1,323 +0,0 @@ -// -// Search input and autocomplete -// - -.search { - position: relative; - z-index: 2; - flex-grow: 1; - height: $sp-10; - padding: $sp-2; - transition: padding linear #{$transition-duration / 2}; - - @include mq(md) { - position: relative !important; - width: auto !important; - height: 100% !important; - padding: 0; - transition: none; - } -} - -.search-input-wrap { - position: relative; - z-index: 1; - height: $sp-8; - overflow: hidden; - border-radius: $border-radius; - box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); - transition: height linear #{$transition-duration / 2}; - - @include mq(md) { - position: absolute; - width: 100%; - max-width: $search-results-width; - height: 100% !important; - border-radius: 0; - box-shadow: none; - transition: width ease $transition-duration; - } -} - -.search-input { - position: absolute; - width: 100%; - height: 100%; - padding-top: $sp-2; - padding-right: $gutter-spacing-sm; - padding-bottom: $sp-2; - padding-left: #{$gutter-spacing-sm + $sp-5}; - font-size: 16px; - background-color: $search-background-color; - border-top: 0; - border-right: 0; - border-bottom: 0; - border-left: 0; - border-radius: 0; - - @include mq(md) { - padding-top: $gutter-spacing-sm; - padding-bottom: $gutter-spacing-sm; - padding-left: #{$gutter-spacing + $sp-5}; - font-size: 14px; - background-color: $body-background-color; - transition: padding-left linear #{$transition-duration / 2}; - } - - &:focus { - outline: 0; - - + .search-label .search-icon { - color: $link-color; - } - } -} - -.search-label { - position: absolute; - display: flex; - height: 100%; - padding-left: $gutter-spacing-sm; - - @include mq(md) { - padding-left: $gutter-spacing; - transition: padding-left linear #{$transition-duration / 2}; - } - - .search-icon { - width: #{$sp-4 * 1.2}; - height: #{$sp-4 * 1.2}; - align-self: center; - color: $grey-dk-000; - } -} - -.search-results { - position: absolute; - left: 0; - display: none; - width: 100%; - max-height: calc(100% - #{$sp-10}); - overflow-y: auto; - background-color: $search-background-color; - border-bottom-right-radius: $border-radius; - border-bottom-left-radius: $border-radius; - box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); - - @include mq(md) { - top: 100%; - width: $search-results-width; - max-height: calc(100vh - 200%) !important; - } -} - -.search-results-list { - padding-left: 0; - margin-bottom: $sp-1; - list-style: none; - @include fs-4; - - @include mq(md) { - @include fs-3; - } -} - -.search-results-list-item { - padding: 0; - margin: 0; -} - -.search-result { - display: block; - padding-top: $sp-1; - padding-right: $sp-3; - padding-bottom: $sp-1; - padding-left: $sp-3; - - &:hover, - &.active { - background-color: $feedback-color; - } -} - -.search-result-title { - display: block; - padding-top: $sp-2; - padding-bottom: $sp-2; - - @include mq(sm) { - display: inline-block; - width: 40%; - padding-right: $sp-2; - vertical-align: top; - } -} - -.search-result-doc { - display: flex; - align-items: center; - word-wrap: break-word; - - &.search-result-doc-parent { - opacity: 0.5; - @include fs-3; - - @include mq(md) { - @include fs-2; - } - } - - .search-result-icon { - width: $sp-4; - height: $sp-4; - margin-right: $sp-2; - color: $link-color; - flex-shrink: 0; - } - - .search-result-doc-title { - overflow: auto; - } -} - -.search-result-section { - margin-left: #{$sp-4 + $sp-2}; - word-wrap: break-word; -} - -.search-result-rel-url { - display: block; - margin-left: #{$sp-4 + $sp-2}; - overflow: hidden; - color: $search-result-preview-color; - text-overflow: ellipsis; - white-space: nowrap; - @include fs-1; -} - -.search-result-previews { - display: block; - padding-top: $sp-2; - padding-bottom: $sp-2; - padding-left: $sp-4; - margin-left: $sp-2; - color: $search-result-preview-color; - word-wrap: break-word; - border-left: $border; - border-left-color: $border-color; - @include fs-2; - - @include mq(sm) { - display: inline-block; - width: 60%; - padding-left: $sp-2; - margin-left: 0; - vertical-align: top; - } -} - -.search-result-preview + .search-result-preview { - margin-top: $sp-1; -} - -.search-result-highlight { - font-weight: bold; -} - -.search-no-result { - padding-top: $sp-2; - padding-right: $sp-3; - padding-bottom: $sp-2; - padding-left: $sp-3; - @include fs-3; -} - -.search-button { - position: fixed; - right: $sp-4; - bottom: $sp-4; - display: flex; - width: $sp-9; - height: $sp-9; - background-color: $search-background-color; - border: 1px solid rgba($link-color, 0.3); - border-radius: #{$sp-9 / 2}; - box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); - align-items: center; - justify-content: center; -} - -.search-overlay { - position: fixed; - top: 0; - left: 0; - z-index: 1; - width: 0; - height: 0; - background-color: rgba(0, 0, 0, 0.3); - opacity: 0; - transition: opacity ease $transition-duration, width 0s $transition-duration, - height 0s $transition-duration; -} - -.search-active { - .search { - position: fixed; - top: 0; - left: 0; - width: 100%; - height: 100%; - padding: 0; - } - - .search-input-wrap { - height: $sp-10; - border-radius: 0; - - @include mq(md) { - width: $search-results-width; - box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); - } - } - - .search-input { - background-color: $search-background-color; - - @include mq(md) { - padding-left: 2.3rem; - } - } - - .search-label { - @include mq(md) { - padding-left: 0.6rem; - } - } - - .search-results { - display: block; - } - - .search-overlay { - width: 100%; - height: 100%; - opacity: 1; - transition: opacity ease $transition-duration, width 0s, height 0s; - } - - @include mq(md) { - .main { - position: fixed; - right: 0; - left: 0; - } - } - - .main-header { - padding-top: $sp-10; - - @include mq(md) { - padding-top: 0; - } - } -} diff --git a/docs/_sass/support/_functions.scss b/docs/_sass/support/_functions.scss deleted file mode 100644 index 6772f4e42..000000000 --- a/docs/_sass/support/_functions.scss +++ /dev/null @@ -1,9 +0,0 @@ -@function rem($size, $unit: "") { - $remSize: $size / $root-font-size; - - @if ($unit == false) { - @return #{$remSize}; - } @else { - @return #{$remSize}rem; - } -} diff --git a/docs/_sass/support/_variables.scss b/docs/_sass/support/_variables.scss deleted file mode 100644 index 3ab3f05e1..000000000 --- a/docs/_sass/support/_variables.scss +++ /dev/null @@ -1,153 +0,0 @@ -// -// Typography -// - -$body-font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", - Roboto, "Helvetica Neue", Arial, sans-serif !default; -$mono-font-family: "SFMono-Regular", Menlo, Consolas, Monospace !default; -$root-font-size: 16px !default; // Base font-size for rems -$body-line-height: 1.4 !default; -$content-line-height: 1.6 !default; -$body-heading-line-height: 1.25 !default; - -// -// Font size -// `-sm` suffix is the size at the small (and above) media query -// - -$font-size-1: 9px !default; -$font-size-1-sm: 10px !default; -$font-size-2: 11px !default; //h4 - uppercased!, h6 not uppercased, text-small -$font-size-3: 12px !default; //h5 -$font-size-4: 14px !default; -$font-size-5: 16px !default; //h3 -$font-size-6: 18px !default; //h2 -$font-size-7: 24px !default; -$font-size-8: 32px !default; //h1 -$font-size-9: 36px !default; -$font-size-10: 42px !default; -$font-size-10-sm: 48px !default; - -// -// Colors -// - -$white: #fff !default; - -$grey-dk-000: #959396 !default; -$grey-dk-100: #5c5962 !default; -$grey-dk-200: #44434d !default; -$grey-dk-250: #302d36 !default; -$grey-dk-300: #27262b !default; - -$grey-lt-000: #f5f6fa !default; -$grey-lt-100: #eeebee !default; -$grey-lt-200: #ecebed !default; -$grey-lt-300: #e6e1e8 !default; - -$purple-000: #7253ed !default; -$purple-100: #5e41d0 !default; -$purple-200: #4e26af !default; -$purple-300: #381885 !default; - -$blue-000: #2c84fa !default; -$blue-100: #2869e6 !default; -$blue-200: #264caf !default; -$blue-300: #183385 !default; - -$green-000: #41d693 !default; -$green-100: #11b584 !default; -$green-200: #009c7b !default; -$green-300: #026e57 !default; - -$yellow-000: #ffeb82 !default; -$yellow-100: #fadf50 !default; -$yellow-200: #f7d12e !default; -$yellow-300: #e7af06 !default; - -$red-000: #f77e7e !default; -$red-100: #f96e65 !default; -$red-200: #e94c4c !default; -$red-300: #dd2e2e !default; - -$body-background-color: $white !default; -$sidebar-color: $grey-lt-000 !default; -$search-background-color: $white !default; -$table-background-color: $white !default; -$code-background-color: $grey-lt-000 !default; -$feedback-color: darken($sidebar-color, 3%) !default; - -$body-text-color: $grey-dk-100 !default; -$body-heading-color: $grey-dk-300 !default; -$search-result-preview-color: $grey-dk-000 !default; -$nav-child-link-color: $grey-dk-100 !default; -$link-color: $purple-000 !default; -$btn-primary-color: $purple-100 !default; -$base-button-color: #f7f7f7 !default; - -// -// Spacing -// - -$spacing-unit: 1rem; // 1rem == 16px - -$spacers: ( - sp-0: 0, - sp-1: $spacing-unit * 0.25, - sp-2: $spacing-unit * 0.5, - sp-3: $spacing-unit * 0.75, - sp-4: $spacing-unit, - sp-5: $spacing-unit * 1.5, - sp-6: $spacing-unit * 2, - sp-7: $spacing-unit * 2.5, - sp-8: $spacing-unit * 3, - sp-9: $spacing-unit * 3.5, - sp-10: $spacing-unit * 4, -) !default; - -$sp-1: map-get($spacers, sp-1) !default; // 0.25 rem == 4px -$sp-2: map-get($spacers, sp-2) !default; // 0.5 rem == 8px -$sp-3: map-get($spacers, sp-3) !default; // 0.75 rem == 12px -$sp-4: map-get($spacers, sp-4) !default; // 1 rem == 16px -$sp-5: map-get($spacers, sp-5) !default; // 1.5 rem == 24px -$sp-6: map-get($spacers, sp-6) !default; // 2 rem == 32px -$sp-7: map-get($spacers, sp-7) !default; // 2.5 rem == 40px -$sp-8: map-get($spacers, sp-8) !default; // 3 rem == 48px -$sp-9: map-get($spacers, sp-9) !default; // 3.5 rem == 56px -$sp-10: map-get($spacers, sp-10) !default; // 4 rem == 64px - -// -// Borders -// - -$border: 1px solid !default; -$border-radius: 4px !default; -$border-color: $grey-lt-100 !default; - -// -// Grid system -// - -$gutter-spacing: $sp-6 !default; -$gutter-spacing-sm: $sp-4 !default; -$nav-width: 264px !default; -$nav-width-md: 248px !default; -$nav-list-item-height: $sp-6 !default; -$nav-list-item-height-sm: $sp-8 !default; -$nav-list-expander-right: true; -$content-width: 800px !default; -$header-height: 60px !default; -$search-results-width: $content-width - $nav-width !default; -$transition-duration: 400ms; - -// -// Media queries in pixels -// - -$media-queries: ( - xs: 320px, - sm: 500px, - md: $content-width, - lg: $content-width + $nav-width, - xl: 1400px, -) !default; diff --git a/docs/_sass/support/mixins/_buttons.scss b/docs/_sass/support/mixins/_buttons.scss deleted file mode 100644 index e3e6c4fbc..000000000 --- a/docs/_sass/support/mixins/_buttons.scss +++ /dev/null @@ -1,27 +0,0 @@ -// Colored button - -@mixin btn-color($fg, $bg) { - color: $fg; - background-color: darken($bg, 2%); - background-image: linear-gradient(lighten($bg, 5%), darken($bg, 2%)); - box-shadow: 0 1px 3px rgba(0, 0, 0, 0.25), 0 4px 10px rgba(0, 0, 0, 0.12); - - &:hover, - &.zeroclipboard-is-hover { - color: $fg; - background-color: darken($bg, 4%); - background-image: linear-gradient((lighten($bg, 2%), darken($bg, 4%))); - } - - &:active, - &.selected, - &.zeroclipboard-is-active { - background-color: darken($bg, 5%); - background-image: none; - box-shadow: inset 0 2px 4px rgba(0, 0, 0, 0.15); - } - - &.selected:hover { - background-color: darken($bg, 10%); - } -} diff --git a/docs/_sass/support/mixins/_layout.scss b/docs/_sass/support/mixins/_layout.scss deleted file mode 100644 index 27ad6c7d9..000000000 --- a/docs/_sass/support/mixins/_layout.scss +++ /dev/null @@ -1,34 +0,0 @@ -// Media query - -// Media query mixin -// Usage: -// @include mq(md) { -// ..medium and up styles -// } -@mixin mq($name) { - // Retrieves the value from the key - $value: map-get($media-queries, $name); - - // If the key exists in the map - @if $value != null { - // Prints a media query based on the value - @media (min-width: rem($value)) { - @content; - } - } @else { - @warn "No value could be retrieved from `#{$media-query}`. " - + "Please make sure it is defined in `$media-queries` map."; - } -} - -// Responsive container - -@mixin container { - padding-right: $gutter-spacing-sm; - padding-left: $gutter-spacing-sm; - - @include mq(md) { - padding-right: $gutter-spacing; - padding-left: $gutter-spacing; - } -} diff --git a/docs/_sass/support/mixins/_typography.scss b/docs/_sass/support/mixins/_typography.scss deleted file mode 100644 index 5207fcd13..000000000 --- a/docs/_sass/support/mixins/_typography.scss +++ /dev/null @@ -1,84 +0,0 @@ -@mixin fs-1 { - font-size: $font-size-1 !important; - - @include mq(sm) { - font-size: $font-size-1-sm !important; - } -} - -@mixin fs-2 { - font-size: $font-size-2 !important; - - @include mq(sm) { - font-size: $font-size-3 !important; - } -} - -@mixin fs-3 { - font-size: $font-size-3 !important; - - @include mq(sm) { - font-size: $font-size-4 !important; - } -} - -@mixin fs-4 { - font-size: $font-size-4 !important; - - @include mq(sm) { - font-size: $font-size-5 !important; - } -} - -@mixin fs-5 { - font-size: $font-size-5 !important; - - @include mq(sm) { - font-size: $font-size-6 !important; - } -} - -@mixin fs-6 { - font-size: $font-size-6 !important; - - @include mq(sm) { - font-size: $font-size-7 !important; - line-height: $body-heading-line-height; - } -} - -@mixin fs-7 { - font-size: $font-size-7 !important; - line-height: $body-heading-line-height; - - @include mq(sm) { - font-size: $font-size-8 !important; - } -} - -@mixin fs-8 { - font-size: $font-size-8 !important; - line-height: $body-heading-line-height; - - @include mq(sm) { - font-size: $font-size-9 !important; - } -} - -@mixin fs-9 { - font-size: $font-size-9 !important; - line-height: $body-heading-line-height; - - @include mq(sm) { - font-size: $font-size-10 !important; - } -} - -@mixin fs-10 { - font-size: $font-size-10 !important; - line-height: $body-heading-line-height; - - @include mq(sm) { - font-size: $font-size-10-sm !important; - } -} diff --git a/docs/_sass/support/mixins/mixins.scss b/docs/_sass/support/mixins/mixins.scss deleted file mode 100644 index 0506fbf5f..000000000 --- a/docs/_sass/support/mixins/mixins.scss +++ /dev/null @@ -1,3 +0,0 @@ -@import "./layout"; -@import "./buttons"; -@import "./typography"; diff --git a/docs/_sass/support/support.scss b/docs/_sass/support/support.scss deleted file mode 100644 index 8131a3201..000000000 --- a/docs/_sass/support/support.scss +++ /dev/null @@ -1,3 +0,0 @@ -@import "./variables"; -@import "./functions"; -@import "./mixins/mixins"; diff --git a/docs/_sass/tables.scss b/docs/_sass/tables.scss deleted file mode 100644 index b2ac7cdb8..000000000 --- a/docs/_sass/tables.scss +++ /dev/null @@ -1,58 +0,0 @@ -// -// Tables -// -// stylelint-disable max-nesting-depth, selector-no-type, selector-max-type - -.table-wrapper { - display: block; - width: 100%; - max-width: 100%; - margin-bottom: $sp-5; - overflow-x: auto; - border-radius: $border-radius; - box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08); -} - -table { - display: table; - min-width: 100%; - border-collapse: separate; -} - -th, -td { - @include fs-3; - min-width: 120px; - padding-top: $sp-2; - padding-right: $sp-3; - padding-bottom: $sp-2; - padding-left: $sp-3; - background-color: $table-background-color; - border-bottom: $border rgba($border-color, 0.5); - border-left: $border $border-color; - - &:first-of-type { - border-left: 0; - } -} - -tbody { - tr { - &:last-of-type { - th, - td { - border-bottom: 0; - } - - td { - padding-bottom: $sp-3; - } - } - } -} - -thead { - th { - border-bottom: $border $border-color; - } -} diff --git a/docs/_sass/typography.scss b/docs/_sass/typography.scss deleted file mode 100644 index cadee362d..000000000 --- a/docs/_sass/typography.scss +++ /dev/null @@ -1,64 +0,0 @@ -// -// Typography -// -// stylelint-disable primer/selector-no-utility, primer/no-override, selector-no-type, selector-max-type - -h1, -.text-alpha { - @include fs-8; - font-weight: 300; -} - -h2, -.text-beta { - @include fs-6; -} - -h3, -.text-gamma { - @include fs-5; -} - -h4, -.text-delta { - @include fs-2; - font-weight: 400; - text-transform: uppercase; - letter-spacing: 0.1em; -} - -h4 code { - text-transform: none; -} - -h5, -.text-epsilon { - @include fs-3; - color: $grey-dk-200; -} - -h6, -.text-zeta { - @include fs-2; - color: $grey-dk-200; -} - -.text-small { - @include fs-2; -} - -.text-mono { - font-family: $mono-font-family !important; -} - -.text-left { - text-align: left !important; -} - -.text-center { - text-align: center !important; -} - -.text-right { - text-align: right !important; -} diff --git a/docs/_sass/utilities/_colors.scss b/docs/_sass/utilities/_colors.scss deleted file mode 100644 index f3607ab89..000000000 --- a/docs/_sass/utilities/_colors.scss +++ /dev/null @@ -1,239 +0,0 @@ -// -// Utility classes for colors -// - -// Text colors - -.text-grey-dk-000 { - color: $grey-dk-000 !important; -} - -.text-grey-dk-100 { - color: $grey-dk-100 !important; -} - -.text-grey-dk-200 { - color: $grey-dk-200 !important; -} - -.text-grey-dk-250 { - color: $grey-dk-250 !important; -} - -.text-grey-dk-300 { - color: $grey-dk-300 !important; -} - -.text-grey-lt-000 { - color: $grey-lt-000 !important; -} - -.text-grey-lt-100 { - color: $grey-lt-100 !important; -} - -.text-grey-lt-200 { - color: $grey-lt-200 !important; -} - -.text-grey-lt-300 { - color: $grey-lt-300 !important; -} - -.text-blue-000 { - color: $blue-000 !important; -} - -.text-blue-100 { - color: $blue-100 !important; -} - -.text-blue-200 { - color: $blue-200 !important; -} - -.text-blue-300 { - color: $blue-300 !important; -} - -.text-green-000 { - color: $green-000 !important; -} - -.text-green-100 { - color: $green-100 !important; -} - -.text-green-200 { - color: $green-200 !important; -} - -.text-green-300 { - color: $green-300 !important; -} - -.text-purple-000 { - color: $purple-000 !important; -} - -.text-purple-100 { - color: $purple-100 !important; -} - -.text-purple-200 { - color: $purple-200 !important; -} - -.text-purple-300 { - color: $purple-300 !important; -} - -.text-yellow-000 { - color: $yellow-000 !important; -} - -.text-yellow-100 { - color: $yellow-100 !important; -} - -.text-yellow-200 { - color: $yellow-200 !important; -} - -.text-yellow-300 { - color: $yellow-300 !important; -} - -.text-red-000 { - color: $red-000 !important; -} - -.text-red-100 { - color: $red-100 !important; -} - -.text-red-200 { - color: $red-200 !important; -} - -.text-red-300 { - color: $red-300 !important; -} - -// Background colors - -.bg-grey-dk-000 { - background-color: $grey-dk-000 !important; -} - -.bg-grey-dk-100 { - background-color: $grey-dk-100 !important; -} - -.bg-grey-dk-200 { - background-color: $grey-dk-200 !important; -} - -.bg-grey-dk-250 { - background-color: $grey-dk-250 !important; -} - -.bg-grey-dk-300 { - background-color: $grey-dk-300 !important; -} - -.bg-grey-lt-000 { - background-color: $grey-lt-000 !important; -} - -.bg-grey-lt-100 { - background-color: $grey-lt-100 !important; -} - -.bg-grey-lt-200 { - background-color: $grey-lt-200 !important; -} - -.bg-grey-lt-300 { - background-color: $grey-lt-300 !important; -} - -.bg-blue-000 { - background-color: $blue-000 !important; -} - -.bg-blue-100 { - background-color: $blue-100 !important; -} - -.bg-blue-200 { - background-color: $blue-200 !important; -} - -.bg-blue-300 { - background-color: $blue-300 !important; -} - -.bg-green-000 { - background-color: $green-000 !important; -} - -.bg-green-100 { - background-color: $green-100 !important; -} - -.bg-green-200 { - background-color: $green-200 !important; -} - -.bg-green-300 { - background-color: $green-300 !important; -} - -.bg-purple-000 { - background-color: $purple-000 !important; -} - -.bg-purple-100 { - background-color: $purple-100 !important; -} - -.bg-purple-200 { - background-color: $purple-200 !important; -} - -.bg-purple-300 { - background-color: $purple-300 !important; -} - -.bg-yellow-000 { - background-color: $yellow-000 !important; -} - -.bg-yellow-100 { - background-color: $yellow-100 !important; -} - -.bg-yellow-200 { - background-color: $yellow-200 !important; -} - -.bg-yellow-300 { - background-color: $yellow-300 !important; -} - -.bg-red-000 { - background-color: $red-000 !important; -} - -.bg-red-100 { - background-color: $red-100 !important; -} - -.bg-red-200 { - background-color: $red-200 !important; -} - -.bg-red-300 { - background-color: $red-300 !important; -} diff --git a/docs/_sass/utilities/_layout.scss b/docs/_sass/utilities/_layout.scss deleted file mode 100644 index 37ebe4214..000000000 --- a/docs/_sass/utilities/_layout.scss +++ /dev/null @@ -1,95 +0,0 @@ -// stylelint-disable primer/selector-no-utility, primer/no-override -// -// Utility classes for layout -// - -// Display - -.d-block { - display: block !important; -} -.d-flex { - display: flex !important; -} -.d-inline { - display: inline !important; -} -.d-inline-block { - display: inline-block !important; -} -.d-none { - display: none !important; -} - -@each $media-query in map-keys($media-queries) { - @for $i from 1 through length($spacers) { - @include mq($media-query) { - $size: #{map-get($spacers, sp-#{$i - 1})}; - $scale: #{$i - 1}; - - // .d-sm-block, .d-md-none, .d-lg-inline - .d-#{$media-query}-block { - display: block !important; - } - .d-#{$media-query}-flex { - display: flex !important; - } - .d-#{$media-query}-inline { - display: inline !important; - } - .d-#{$media-query}-inline-block { - display: inline-block !important; - } - .d-#{$media-query}-none { - display: none !important; - } - } - } -} - -// Horizontal alignment - -.float-left { - float: left !important; -} - -.float-right { - float: right !important; -} - -.flex-justify-start { - justify-content: flex-start !important; -} - -.flex-justify-end { - justify-content: flex-end !important; -} - -.flex-justify-between { - justify-content: space-between !important; -} - -.flex-justify-around { - justify-content: space-around !important; -} - -// Vertical alignment - -.v-align-baseline { - vertical-align: baseline !important; -} -.v-align-bottom { - vertical-align: bottom !important; -} -.v-align-middle { - vertical-align: middle !important; -} -.v-align-text-bottom { - vertical-align: text-bottom !important; -} -.v-align-text-top { - vertical-align: text-top !important; -} -.v-align-top { - vertical-align: top !important; -} diff --git a/docs/_sass/utilities/_lists.scss b/docs/_sass/utilities/_lists.scss deleted file mode 100644 index c7b2293d0..000000000 --- a/docs/_sass/utilities/_lists.scss +++ /dev/null @@ -1,17 +0,0 @@ -// -// Utility classes for lists -// - -// stylelint-disable primer/selector-no-utility, primer/no-override, selector-max-type - -.list-style-none { - padding: 0 !important; - margin: 0 !important; - list-style: none !important; - - li { - &::before { - display: none !important; - } - } -} diff --git a/docs/_sass/utilities/_spacing.scss b/docs/_sass/utilities/_spacing.scss deleted file mode 100644 index 162f8017a..000000000 --- a/docs/_sass/utilities/_spacing.scss +++ /dev/null @@ -1,165 +0,0 @@ -// -// Utility classes for margins and padding -// - -// scss-lint:disable SpaceAfterPropertyName -// stylelint-disable block-opening-brace-space-after, block-opening-brace-space-before, primer/selector-no-utility, primer/no-override - -// Margin spacer utilities - -.mx-auto { - margin-right: auto !important; - margin-left: auto !important; -} - -@for $i from 1 through length($spacers) { - $size: #{map-get($spacers, sp-#{$i - 1})}; - $scale: #{$i - 1}; - - // .m-0, .m-1, .m-2... - .m-#{$scale} { - margin: #{$size} !important; - } - .mt-#{$scale} { - margin-top: #{$size} !important; - } - .mr-#{$scale} { - margin-right: #{$size} !important; - } - .mb-#{$scale} { - margin-bottom: #{$size} !important; - } - .ml-#{$scale} { - margin-left: #{$size} !important; - } - - .mx-#{$scale} { - margin-right: #{$size} !important; - margin-left: #{$size} !important; - } - - .my-#{$scale} { - margin-top: #{$size} !important; - margin-bottom: #{$size} !important; - } - - .mxn-#{$scale} { - margin-right: -#{$size} !important; - margin-left: -#{$size} !important; - } - .mx-#{$scale}-auto { - margin-right: auto !important; - margin-left: auto !important; - } -} - -@each $media-query in map-keys($media-queries) { - @for $i from 1 through length($spacers) { - @include mq($media-query) { - $size: #{map-get($spacers, sp-#{$i - 1})}; - $scale: #{$i - 1}; - - // .m-sm-0, .m-md-1, .m-lg-2... - .m-#{$media-query}-#{$scale} { - margin: #{$size} !important; - } - .mt-#{$media-query}-#{$scale} { - margin-top: #{$size} !important; - } - .mr-#{$media-query}-#{$scale} { - margin-right: #{$size} !important; - } - .mb-#{$media-query}-#{$scale} { - margin-bottom: #{$size} !important; - } - .ml-#{$media-query}-#{$scale} { - margin-left: #{$size} !important; - } - - .mx-#{$media-query}-#{$scale} { - margin-right: #{$size} !important; - margin-left: #{$size} !important; - } - - .my-#{$media-query}-#{$scale} { - margin-top: #{$size} !important; - margin-bottom: #{$size} !important; - } - - .mxn-#{$media-query}-#{$scale} { - margin-right: -#{$size} !important; - margin-left: -#{$size} !important; - } - } - } -} - -// Padding spacer utilities - -@for $i from 1 through length($spacers) { - $size: #{map-get($spacers, sp-#{$i - 1})}; - $scale: #{$i - 1}; - - // .p-0, .p-1, .p-2... - .p-#{$scale} { - padding: #{$size} !important; - } - .pt-#{$scale} { - padding-top: #{$size} !important; - } - .pr-#{$scale} { - padding-right: #{$size} !important; - } - .pb-#{$scale} { - padding-bottom: #{$size} !important; - } - .pl-#{$scale} { - padding-left: #{$size} !important; - } - - .px-#{$scale} { - padding-right: #{$size} !important; - padding-left: #{$size} !important; - } - - .py-#{$scale} { - padding-top: #{$size} !important; - padding-bottom: #{$size} !important; - } -} - -@each $media-query in map-keys($media-queries) { - @include mq($media-query) { - @for $i from 1 through length($spacers) { - $size: #{map-get($spacers, sp-#{$i - 1})}; - $scale: #{$i - 1}; - - // .p-sm-0, .p-md-1, .p-lg-2... - .p-#{$media-query}-#{$scale} { - padding: #{$size} !important; - } - .pt-#{$media-query}-#{$scale} { - padding-top: #{$size} !important; - } - .pr-#{$media-query}-#{$scale} { - padding-right: #{$size} !important; - } - .pb-#{$media-query}-#{$scale} { - padding-bottom: #{$size} !important; - } - .pl-#{$media-query}-#{$scale} { - padding-left: #{$size} !important; - } - - .px-#{$media-query}-#{$scale} { - padding-right: #{$size} !important; - padding-left: #{$size} !important; - } - - .py-#{$media-query}-#{$scale} { - padding-top: #{$size} !important; - padding-bottom: #{$size} !important; - } - } - } -} diff --git a/docs/_sass/utilities/_typography.scss b/docs/_sass/utilities/_typography.scss deleted file mode 100644 index 2397acbc0..000000000 --- a/docs/_sass/utilities/_typography.scss +++ /dev/null @@ -1,91 +0,0 @@ -// -// Utility classes for typography -// - -// stylelint-disable primer/selector-no-utility, primer/no-override - -.fs-1 { - @include fs-1; -} - -.fs-2 { - @include fs-2; -} - -.fs-3 { - @include fs-3; -} - -.fs-4 { - @include fs-4; -} - -.fs-5 { - @include fs-5; -} - -.fs-6 { - @include fs-6; -} - -.fs-7 { - @include fs-7; -} - -.fs-8 { - @include fs-8; -} - -.fs-9 { - @include fs-9; -} - -.fs-10 { - @include fs-10; -} - -.fw-300 { - font-weight: 300 !important; -} - -.fw-400 { - font-weight: 400 !important; -} - -.fw-500 { - font-weight: 500 !important; -} - -.fw-700 { - font-weight: 700 !important; -} - -.lh-0 { - line-height: 0 !important; -} - -.lh-default { - line-height: $body-line-height; -} - -.lh-tight { - line-height: $body-heading-line-height; -} - -.ls-5 { - letter-spacing: 0.05em !important; -} - -.ls-10 { - letter-spacing: 0.1em !important; -} - -.ls-0 { - letter-spacing: 0 !important; -} - -.text-uppercase { - text-transform: uppercase !important; -} - -// stylelint-enable primer/selector-no-utility diff --git a/docs/_sass/utilities/utilities.scss b/docs/_sass/utilities/utilities.scss deleted file mode 100644 index 6c25bdfa7..000000000 --- a/docs/_sass/utilities/utilities.scss +++ /dev/null @@ -1,5 +0,0 @@ -@import "./colors"; -@import "./layout"; -@import "./typography"; -@import "./lists"; -@import "./spacing"; diff --git a/docs/_sass/vendor/normalize.scss/README.md b/docs/_sass/vendor/normalize.scss/README.md deleted file mode 100644 index 7af1714a9..000000000 --- a/docs/_sass/vendor/normalize.scss/README.md +++ /dev/null @@ -1,7 +0,0 @@ -# normalize.scss - -Normalize.scss is an SCSS copy of [normalize.css](http://necolas.github.io/normalize.css), a customisable CSS file that makes browsers render all elements more consistently and in line with modern standards. - -The [normalize.scss fork](https://github.com/guerrero/normalize.scss) of [normalize.css](http://necolas.github.io/normalize.css) was archived in 2014, and has not been updated since v0.1.0. - -[View the normalize.css test file](http://necolas.github.io/normalize.css/latest/test.html) diff --git a/docs/_sass/vendor/normalize.scss/normalize.scss b/docs/_sass/vendor/normalize.scss/normalize.scss deleted file mode 100644 index 192eb9ce4..000000000 --- a/docs/_sass/vendor/normalize.scss/normalize.scss +++ /dev/null @@ -1,349 +0,0 @@ -/*! normalize.css v8.0.1 | MIT License | github.com/necolas/normalize.css */ - -/* Document - ========================================================================== */ - -/** - * 1. Correct the line height in all browsers. - * 2. Prevent adjustments of font size after orientation changes in iOS. - */ - -html { - line-height: 1.15; /* 1 */ - -webkit-text-size-adjust: 100%; /* 2 */ -} - -/* Sections - ========================================================================== */ - -/** - * Remove the margin in all browsers. - */ - -body { - margin: 0; -} - -/** - * Render the `main` element consistently in IE. - */ - -main { - display: block; -} - -/** - * Correct the font size and margin on `h1` elements within `section` and - * `article` contexts in Chrome, Firefox, and Safari. - */ - -h1 { - font-size: 2em; - margin: 0.67em 0; -} - -/* Grouping content - ========================================================================== */ - -/** - * 1. Add the correct box sizing in Firefox. - * 2. Show the overflow in Edge and IE. - */ - -hr { - box-sizing: content-box; /* 1 */ - height: 0; /* 1 */ - overflow: visible; /* 2 */ -} - -/** - * 1. Correct the inheritance and scaling of font size in all browsers. - * 2. Correct the odd `em` font sizing in all browsers. - */ - -pre { - font-family: monospace, monospace; /* 1 */ - font-size: 1em; /* 2 */ -} - -/* Text-level semantics - ========================================================================== */ - -/** - * Remove the gray background on active links in IE 10. - */ - -a { - background-color: transparent; -} - -/** - * 1. Remove the bottom border in Chrome 57- - * 2. Add the correct text decoration in Chrome, Edge, IE, Opera, and Safari. - */ - -abbr[title] { - border-bottom: none; /* 1 */ - text-decoration: underline; /* 2 */ - text-decoration: underline dotted; /* 2 */ -} - -/** - * Add the correct font weight in Chrome, Edge, and Safari. - */ - -b, -strong { - font-weight: bolder; -} - -/** - * 1. Correct the inheritance and scaling of font size in all browsers. - * 2. Correct the odd `em` font sizing in all browsers. - */ - -code, -kbd, -samp { - font-family: monospace, monospace; /* 1 */ - font-size: 1em; /* 2 */ -} - -/** - * Add the correct font size in all browsers. - */ - -small { - font-size: 80%; -} - -/** - * Prevent `sub` and `sup` elements from affecting the line height in - * all browsers. - */ - -sub, -sup { - font-size: 75%; - line-height: 0; - position: relative; - vertical-align: baseline; -} - -sub { - bottom: -0.25em; -} - -sup { - top: -0.5em; -} - -/* Embedded content - ========================================================================== */ - -/** - * Remove the border on images inside links in IE 10. - */ - -img { - border-style: none; -} - -/* Forms - ========================================================================== */ - -/** - * 1. Change the font styles in all browsers. - * 2. Remove the margin in Firefox and Safari. - */ - -button, -input, -optgroup, -select, -textarea { - font-family: inherit; /* 1 */ - font-size: 100%; /* 1 */ - line-height: 1.15; /* 1 */ - margin: 0; /* 2 */ -} - -/** - * Show the overflow in IE. - * 1. Show the overflow in Edge. - */ - -button, -input { /* 1 */ - overflow: visible; -} - -/** - * Remove the inheritance of text transform in Edge, Firefox, and IE. - * 1. Remove the inheritance of text transform in Firefox. - */ - -button, -select { /* 1 */ - text-transform: none; -} - -/** - * Correct the inability to style clickable types in iOS and Safari. - */ - -button, -[type="button"], -[type="reset"], -[type="submit"] { - -webkit-appearance: button; -} - -/** - * Remove the inner border and padding in Firefox. - */ - -button::-moz-focus-inner, -[type="button"]::-moz-focus-inner, -[type="reset"]::-moz-focus-inner, -[type="submit"]::-moz-focus-inner { - border-style: none; - padding: 0; -} - -/** - * Restore the focus styles unset by the previous rule. - */ - -button:-moz-focusring, -[type="button"]:-moz-focusring, -[type="reset"]:-moz-focusring, -[type="submit"]:-moz-focusring { - outline: 1px dotted ButtonText; -} - -/** - * Correct the padding in Firefox. - */ - -fieldset { - padding: 0.35em 0.75em 0.625em; -} - -/** - * 1. Correct the text wrapping in Edge and IE. - * 2. Correct the color inheritance from `fieldset` elements in IE. - * 3. Remove the padding so developers are not caught out when they zero out - * `fieldset` elements in all browsers. - */ - -legend { - box-sizing: border-box; /* 1 */ - color: inherit; /* 2 */ - display: table; /* 1 */ - max-width: 100%; /* 1 */ - padding: 0; /* 3 */ - white-space: normal; /* 1 */ -} - -/** - * Add the correct vertical alignment in Chrome, Firefox, and Opera. - */ - -progress { - vertical-align: baseline; -} - -/** - * Remove the default vertical scrollbar in IE 10+. - */ - -textarea { - overflow: auto; -} - -/** - * 1. Add the correct box sizing in IE 10. - * 2. Remove the padding in IE 10. - */ - -[type="checkbox"], -[type="radio"] { - box-sizing: border-box; /* 1 */ - padding: 0; /* 2 */ -} - -/** - * Correct the cursor style of increment and decrement buttons in Chrome. - */ - -[type="number"]::-webkit-inner-spin-button, -[type="number"]::-webkit-outer-spin-button { - height: auto; -} - -/** - * 1. Correct the odd appearance in Chrome and Safari. - * 2. Correct the outline style in Safari. - */ - -[type="search"] { - -webkit-appearance: textfield; /* 1 */ - outline-offset: -2px; /* 2 */ -} - -/** - * Remove the inner padding in Chrome and Safari on macOS. - */ - -[type="search"]::-webkit-search-decoration { - -webkit-appearance: none; -} - -/** - * 1. Correct the inability to style clickable types in iOS and Safari. - * 2. Change font properties to `inherit` in Safari. - */ - -::-webkit-file-upload-button { - -webkit-appearance: button; /* 1 */ - font: inherit; /* 2 */ -} - -/* Interactive - ========================================================================== */ - -/* - * Add the correct display in Edge, IE 10+, and Firefox. - */ - -details { - display: block; -} - -/* - * Add the correct display in all browsers. - */ - -summary { - display: list-item; -} - -/* Misc - ========================================================================== */ - -/** - * Add the correct display in IE 10+. - */ - -template { - display: none; -} - -/** - * Add the correct display in IE 10. - */ - -[hidden] { - display: none; -} diff --git a/docs/architecture/index.md b/docs/architecture/index.md deleted file mode 100644 index 5a28c6025..000000000 --- a/docs/architecture/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -layout: i18n_page -title: pages.architecture -nav_order: 6 -has_children: true ---- - -# Architecture - -This section contains a collection of technical architecture diagrams detailing the various runtime components of a FireFly deployment. diff --git a/docs/architecture/multiparty_event_sequencing.md b/docs/architecture/multiparty_event_sequencing.md deleted file mode 100644 index d49219fec..000000000 --- a/docs/architecture/multiparty_event_sequencing.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -layout: default -title: Multiparty Event Sequencing -parent: pages.architecture -nav_order: 3 ---- - -# Multiparty Event Sequencing -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- - - - -[![Multiparty Event Sequencing](../images/global_sequencing.svg "Multiparty Event Sequencing")](../images/global_sequencing.svg) - -## Transaction Submission - -* An individual FireFly instance preserves the order that it received messages from application instances. -* Where possible, batching is used to roll-up hundreds of transactions into a single blockchain transaction. -* *Blockchain allows these messages to be globally sequenced with messages submitted by other members of the network.* - -## Blockchain Ordering - -* All member FireFly runtimes see every transaction in the same sequence. -* *This includes when transactions are being submitted by both sides concurrently.* - -## Message Assembly - -* A queue of events is maintained for each matching app subscription. -* The public/private payloads travel separately to the blockchain, and arrive at different times. FireFly assembles these together prior to delivery. -* If data associated with a blockchain transaction is late, or does not arrive, all messages on the same "context" will be blocked. -* *It is good practice to send messages that don't need to be processed in order, with different "context" fields. For example use the ID of your business transaction, or other long-running process / customer identifier.* - -## Event Processing - -* Events are processed consistently by all parties. -* All FireFly runtimes see every event that they are subscribed to, in the same sequence. -* *The submitter must also apply the logic only in the sequence ordered by the blockhain. It cannot assume the order even if it is the member that submitted it.* diff --git a/docs/assets/css/just-the-docs-dark.scss b/docs/assets/css/just-the-docs-dark.scss deleted file mode 100644 index ac92fb152..000000000 --- a/docs/assets/css/just-the-docs-dark.scss +++ /dev/null @@ -1,3 +0,0 @@ ---- ---- -{% include css/just-the-docs.scss.liquid color_scheme="dark" %} diff --git a/docs/assets/css/just-the-docs-default.scss b/docs/assets/css/just-the-docs-default.scss deleted file mode 100644 index 63fde26e1..000000000 --- a/docs/assets/css/just-the-docs-default.scss +++ /dev/null @@ -1,8 +0,0 @@ ---- ---- -{% if site.color_scheme and site.color_scheme != "nil" %} - {% assign color_scheme = site.color_scheme %} -{% else %} - {% assign color_scheme = "light" %} -{% endif %} -{% include css/just-the-docs.scss.liquid color_scheme=color_scheme %} diff --git a/docs/assets/css/just-the-docs-light.scss b/docs/assets/css/just-the-docs-light.scss deleted file mode 100644 index ac69688df..000000000 --- a/docs/assets/css/just-the-docs-light.scss +++ /dev/null @@ -1,3 +0,0 @@ ---- ---- -{% include css/just-the-docs.scss.liquid color_scheme="light" %} diff --git a/docs/assets/images/search.svg b/docs/assets/images/search.svg deleted file mode 100644 index 421ca4df0..000000000 --- a/docs/assets/images/search.svg +++ /dev/null @@ -1 +0,0 @@ -Search diff --git a/docs/assets/js/just-the-docs.js b/docs/assets/js/just-the-docs.js deleted file mode 100644 index c287ec08c..000000000 --- a/docs/assets/js/just-the-docs.js +++ /dev/null @@ -1,471 +0,0 @@ ---- ---- -(function (jtd, undefined) { - -// Event handling - -jtd.addEvent = function(el, type, handler) { - if (el.attachEvent) el.attachEvent('on'+type, handler); else el.addEventListener(type, handler); -} -jtd.removeEvent = function(el, type, handler) { - if (el.detachEvent) el.detachEvent('on'+type, handler); else el.removeEventListener(type, handler); -} -jtd.onReady = function(ready) { - // in case the document is already rendered - if (document.readyState!='loading') ready(); - // modern browsers - else if (document.addEventListener) document.addEventListener('DOMContentLoaded', ready); - // IE <= 8 - else document.attachEvent('onreadystatechange', function(){ - if (document.readyState=='complete') ready(); - }); -} - -// Show/hide mobile menu - -function initNav() { - jtd.addEvent(document, 'click', function(e){ - var target = e.target; - while (target && !(target.classList && target.classList.contains('nav-list-expander'))) { - target = target.parentNode; - } - if (target) { - e.preventDefault(); - target.parentNode.classList.toggle('active'); - } - }); - - const siteNav = document.getElementById('site-nav'); - const mainHeader = document.getElementById('main-header'); - const menuButton = document.getElementById('menu-button'); - - jtd.addEvent(menuButton, 'click', function(e){ - e.preventDefault(); - - if (menuButton.classList.toggle('nav-open')) { - siteNav.classList.add('nav-open'); - mainHeader.classList.add('nav-open'); - } else { - siteNav.classList.remove('nav-open'); - mainHeader.classList.remove('nav-open'); - } - }); - - {%- if site.search_enabled != false and site.search.button %} - const searchInput = document.getElementById('search-input'); - const searchButton = document.getElementById('search-button'); - - jtd.addEvent(searchButton, 'click', function(e){ - e.preventDefault(); - - mainHeader.classList.add('nav-open'); - searchInput.focus(); - }); - {%- endif %} -} - -{%- if site.search_enabled != false %} -// Site search - -function initSearch() { - var request = new XMLHttpRequest(); - request.open('GET', '{{ "assets/js/search-data.json" | absolute_url }}', true); - - request.onload = function(){ - if (request.status >= 200 && request.status < 400) { - var docs = JSON.parse(request.responseText); - - lunr.tokenizer.separator = {{ site.search.tokenizer_separator | default: site.search_tokenizer_separator | default: "/[\s\-/]+/" }} - - var index = lunr(function(){ - this.ref('id'); - this.field('title', { boost: 200 }); - this.field('content', { boost: 2 }); - {%- if site.search.rel_url != false %} - this.field('relUrl'); - {%- endif %} - this.metadataWhitelist = ['position'] - - for (var i in docs) { - this.add({ - id: i, - title: docs[i].title, - content: docs[i].content, - {%- if site.search.rel_url != false %} - relUrl: docs[i].relUrl - {%- endif %} - }); - } - }); - - searchLoaded(index, docs); - } else { - console.log('Error loading ajax request. Request status:' + request.status); - } - }; - - request.onerror = function(){ - console.log('There was a connection error'); - }; - - request.send(); -} - -function searchLoaded(index, docs) { - var index = index; - var docs = docs; - var searchInput = document.getElementById('search-input'); - var searchResults = document.getElementById('search-results'); - var mainHeader = document.getElementById('main-header'); - var currentInput; - var currentSearchIndex = 0; - - function showSearch() { - document.documentElement.classList.add('search-active'); - } - - function hideSearch() { - document.documentElement.classList.remove('search-active'); - } - - function update() { - currentSearchIndex++; - - var input = searchInput.value; - if (input === '') { - hideSearch(); - } else { - showSearch(); - // scroll search input into view, workaround for iOS Safari - window.scroll(0, -1); - setTimeout(function(){ window.scroll(0, 0); }, 0); - } - if (input === currentInput) { - return; - } - currentInput = input; - searchResults.innerHTML = ''; - if (input === '') { - return; - } - - var results = index.query(function (query) { - var tokens = lunr.tokenizer(input) - query.term(tokens, { - boost: 10 - }); - query.term(tokens, { - wildcard: lunr.Query.wildcard.TRAILING - }); - }); - - if ((results.length == 0) && (input.length > 2)) { - var tokens = lunr.tokenizer(input).filter(function(token, i) { - return token.str.length < 20; - }) - if (tokens.length > 0) { - results = index.query(function (query) { - query.term(tokens, { - editDistance: Math.round(Math.sqrt(input.length / 2 - 1)) - }); - }); - } - } - - if (results.length == 0) { - var noResultsDiv = document.createElement('div'); - noResultsDiv.classList.add('search-no-result'); - noResultsDiv.innerText = 'No results found'; - searchResults.appendChild(noResultsDiv); - - } else { - var resultsList = document.createElement('ul'); - resultsList.classList.add('search-results-list'); - searchResults.appendChild(resultsList); - - addResults(resultsList, results, 0, 10, 100, currentSearchIndex); - } - - function addResults(resultsList, results, start, batchSize, batchMillis, searchIndex) { - if (searchIndex != currentSearchIndex) { - return; - } - for (var i = start; i < (start + batchSize); i++) { - if (i == results.length) { - return; - } - addResult(resultsList, results[i]); - } - setTimeout(function() { - addResults(resultsList, results, start + batchSize, batchSize, batchMillis, searchIndex); - }, batchMillis); - } - - function addResult(resultsList, result) { - var doc = docs[result.ref]; - - var resultsListItem = document.createElement('li'); - resultsListItem.classList.add('search-results-list-item'); - resultsList.appendChild(resultsListItem); - - var resultLink = document.createElement('a'); - resultLink.classList.add('search-result'); - resultLink.setAttribute('href', doc.url); - resultsListItem.appendChild(resultLink); - - var resultTitle = document.createElement('div'); - resultTitle.classList.add('search-result-title'); - resultLink.appendChild(resultTitle); - - var resultDoc = document.createElement('div'); - resultDoc.classList.add('search-result-doc'); - resultDoc.innerHTML = ''; - resultTitle.appendChild(resultDoc); - - var resultDocTitle = document.createElement('div'); - resultDocTitle.classList.add('search-result-doc-title'); - resultDocTitle.innerHTML = doc.doc; - resultDoc.appendChild(resultDocTitle); - var resultDocOrSection = resultDocTitle; - - if (doc.doc != doc.title) { - resultDoc.classList.add('search-result-doc-parent'); - var resultSection = document.createElement('div'); - resultSection.classList.add('search-result-section'); - resultSection.innerHTML = doc.title; - resultTitle.appendChild(resultSection); - resultDocOrSection = resultSection; - } - - var metadata = result.matchData.metadata; - var titlePositions = []; - var contentPositions = []; - for (var j in metadata) { - var meta = metadata[j]; - if (meta.title) { - var positions = meta.title.position; - for (var k in positions) { - titlePositions.push(positions[k]); - } - } - if (meta.content) { - var positions = meta.content.position; - for (var k in positions) { - var position = positions[k]; - var previewStart = position[0]; - var previewEnd = position[0] + position[1]; - var ellipsesBefore = true; - var ellipsesAfter = true; - for (var k = 0; k < {{ site.search.preview_words_before | default: 5 }}; k++) { - var nextSpace = doc.content.lastIndexOf(' ', previewStart - 2); - var nextDot = doc.content.lastIndexOf('. ', previewStart - 2); - if ((nextDot >= 0) && (nextDot > nextSpace)) { - previewStart = nextDot + 1; - ellipsesBefore = false; - break; - } - if (nextSpace < 0) { - previewStart = 0; - ellipsesBefore = false; - break; - } - previewStart = nextSpace + 1; - } - for (var k = 0; k < {{ site.search.preview_words_after | default: 10 }}; k++) { - var nextSpace = doc.content.indexOf(' ', previewEnd + 1); - var nextDot = doc.content.indexOf('. ', previewEnd + 1); - if ((nextDot >= 0) && (nextDot < nextSpace)) { - previewEnd = nextDot; - ellipsesAfter = false; - break; - } - if (nextSpace < 0) { - previewEnd = doc.content.length; - ellipsesAfter = false; - break; - } - previewEnd = nextSpace; - } - contentPositions.push({ - highlight: position, - previewStart: previewStart, previewEnd: previewEnd, - ellipsesBefore: ellipsesBefore, ellipsesAfter: ellipsesAfter - }); - } - } - } - - if (titlePositions.length > 0) { - titlePositions.sort(function(p1, p2){ return p1[0] - p2[0] }); - resultDocOrSection.innerHTML = ''; - addHighlightedText(resultDocOrSection, doc.title, 0, doc.title.length, titlePositions); - } - - if (contentPositions.length > 0) { - contentPositions.sort(function(p1, p2){ return p1.highlight[0] - p2.highlight[0] }); - var contentPosition = contentPositions[0]; - var previewPosition = { - highlight: [contentPosition.highlight], - previewStart: contentPosition.previewStart, previewEnd: contentPosition.previewEnd, - ellipsesBefore: contentPosition.ellipsesBefore, ellipsesAfter: contentPosition.ellipsesAfter - }; - var previewPositions = [previewPosition]; - for (var j = 1; j < contentPositions.length; j++) { - contentPosition = contentPositions[j]; - if (previewPosition.previewEnd < contentPosition.previewStart) { - previewPosition = { - highlight: [contentPosition.highlight], - previewStart: contentPosition.previewStart, previewEnd: contentPosition.previewEnd, - ellipsesBefore: contentPosition.ellipsesBefore, ellipsesAfter: contentPosition.ellipsesAfter - } - previewPositions.push(previewPosition); - } else { - previewPosition.highlight.push(contentPosition.highlight); - previewPosition.previewEnd = contentPosition.previewEnd; - previewPosition.ellipsesAfter = contentPosition.ellipsesAfter; - } - } - - var resultPreviews = document.createElement('div'); - resultPreviews.classList.add('search-result-previews'); - resultLink.appendChild(resultPreviews); - - var content = doc.content; - for (var j = 0; j < Math.min(previewPositions.length, {{ site.search.previews | default: 3 }}); j++) { - var position = previewPositions[j]; - - var resultPreview = document.createElement('div'); - resultPreview.classList.add('search-result-preview'); - resultPreviews.appendChild(resultPreview); - - if (position.ellipsesBefore) { - resultPreview.appendChild(document.createTextNode('... ')); - } - addHighlightedText(resultPreview, content, position.previewStart, position.previewEnd, position.highlight); - if (position.ellipsesAfter) { - resultPreview.appendChild(document.createTextNode(' ...')); - } - } - } - - {%- if site.search.rel_url != false %} - var resultRelUrl = document.createElement('span'); - resultRelUrl.classList.add('search-result-rel-url'); - resultRelUrl.innerText = doc.relUrl; - resultTitle.appendChild(resultRelUrl); - {%- endif %} - } - - function addHighlightedText(parent, text, start, end, positions) { - var index = start; - for (var i in positions) { - var position = positions[i]; - var span = document.createElement('span'); - span.innerHTML = text.substring(index, position[0]); - parent.appendChild(span); - index = position[0] + position[1]; - var highlight = document.createElement('span'); - highlight.classList.add('search-result-highlight'); - highlight.innerHTML = text.substring(position[0], index); - parent.appendChild(highlight); - } - var span = document.createElement('span'); - span.innerHTML = text.substring(index, end); - parent.appendChild(span); - } - } - - jtd.addEvent(searchInput, 'focus', function(){ - setTimeout(update, 0); - }); - - jtd.addEvent(searchInput, 'keyup', function(e){ - switch (e.keyCode) { - case 27: // When esc key is pressed, hide the results and clear the field - searchInput.value = ''; - break; - case 38: // arrow up - case 40: // arrow down - case 13: // enter - e.preventDefault(); - return; - } - update(); - }); - - jtd.addEvent(searchInput, 'keydown', function(e){ - switch (e.keyCode) { - case 38: // arrow up - e.preventDefault(); - var active = document.querySelector('.search-result.active'); - if (active) { - active.classList.remove('active'); - if (active.parentElement.previousSibling) { - var previous = active.parentElement.previousSibling.querySelector('.search-result'); - previous.classList.add('active'); - } - } - return; - case 40: // arrow down - e.preventDefault(); - var active = document.querySelector('.search-result.active'); - if (active) { - if (active.parentElement.nextSibling) { - var next = active.parentElement.nextSibling.querySelector('.search-result'); - active.classList.remove('active'); - next.classList.add('active'); - } - } else { - var next = document.querySelector('.search-result'); - if (next) { - next.classList.add('active'); - } - } - return; - case 13: // enter - e.preventDefault(); - var active = document.querySelector('.search-result.active'); - if (active) { - active.click(); - } else { - var first = document.querySelector('.search-result'); - if (first) { - first.click(); - } - } - return; - } - }); - - jtd.addEvent(document, 'click', function(e){ - if (e.target != searchInput) { - hideSearch(); - } - }); -} -{%- endif %} - -// Switch theme - -jtd.getTheme = function() { - var cssFileHref = document.querySelector('[rel="stylesheet"]').getAttribute('href'); - return cssFileHref.substring(cssFileHref.lastIndexOf('-') + 1, cssFileHref.length - 4); -} - -jtd.setTheme = function(theme) { - var cssFile = document.querySelector('[rel="stylesheet"]'); - cssFile.setAttribute('href', '{{ "assets/css/just-the-docs-" | absolute_url }}' + theme + '.css'); -} - -// Document ready - -jtd.onReady(function(){ - initNav(); - {%- if site.search_enabled != false %} - initSearch(); - {%- endif %} -}); - -})(window.jtd = window.jtd || {}); - -{% include js/custom.js %} diff --git a/docs/assets/js/vendor/lunr.min.js b/docs/assets/js/vendor/lunr.min.js deleted file mode 100644 index 34b279dac..000000000 --- a/docs/assets/js/vendor/lunr.min.js +++ /dev/null @@ -1,6 +0,0 @@ -/** - * lunr - http://lunrjs.com - A bit like Solr, but much smaller and not as bright - 2.3.6 - * Copyright (C) 2019 Oliver Nightingale - * @license MIT - */ -!function(){var e=function(t){var r=new e.Builder;return r.pipeline.add(e.trimmer,e.stopWordFilter,e.stemmer),r.searchPipeline.add(e.stemmer),t.call(r,r),r.build()};e.version="2.3.6",e.utils={},e.utils.warn=function(e){return function(t){e.console&&console.warn&&console.warn(t)}}(this),e.utils.asString=function(e){return void 0===e||null===e?"":e.toString()},e.utils.clone=function(e){if(null===e||void 0===e)return e;for(var t=Object.create(null),r=Object.keys(e),i=0;i0){var c=e.utils.clone(r)||{};c.position=[a,l],c.index=s.length,s.push(new e.Token(i.slice(a,o),c))}a=o+1}}return s},e.tokenizer.separator=/[\s\-]+/,e.Pipeline=function(){this._stack=[]},e.Pipeline.registeredFunctions=Object.create(null),e.Pipeline.registerFunction=function(t,r){r in this.registeredFunctions&&e.utils.warn("Overwriting existing registered function: "+r),t.label=r,e.Pipeline.registeredFunctions[t.label]=t},e.Pipeline.warnIfFunctionNotRegistered=function(t){var r=t.label&&t.label in this.registeredFunctions;r||e.utils.warn("Function is not registered with pipeline. This may cause problems when serialising the index.\n",t)},e.Pipeline.load=function(t){var r=new e.Pipeline;return t.forEach(function(t){var i=e.Pipeline.registeredFunctions[t];if(!i)throw new Error("Cannot load unregistered function: "+t);r.add(i)}),r},e.Pipeline.prototype.add=function(){var t=Array.prototype.slice.call(arguments);t.forEach(function(t){e.Pipeline.warnIfFunctionNotRegistered(t),this._stack.push(t)},this)},e.Pipeline.prototype.after=function(t,r){e.Pipeline.warnIfFunctionNotRegistered(r);var i=this._stack.indexOf(t);if(i==-1)throw new Error("Cannot find existingFn");i+=1,this._stack.splice(i,0,r)},e.Pipeline.prototype.before=function(t,r){e.Pipeline.warnIfFunctionNotRegistered(r);var i=this._stack.indexOf(t);if(i==-1)throw new Error("Cannot find existingFn");this._stack.splice(i,0,r)},e.Pipeline.prototype.remove=function(e){var t=this._stack.indexOf(e);t!=-1&&this._stack.splice(t,1)},e.Pipeline.prototype.run=function(e){for(var t=this._stack.length,r=0;r1&&(se&&(r=n),s!=e);)i=r-t,n=t+Math.floor(i/2),s=this.elements[2*n];return s==e?2*n:s>e?2*n:sa?l+=2:o==a&&(t+=r[u+1]*i[l+1],u+=2,l+=2);return t},e.Vector.prototype.similarity=function(e){return this.dot(e)/this.magnitude()||0},e.Vector.prototype.toArray=function(){for(var e=new Array(this.elements.length/2),t=1,r=0;t0){var o,a=s.str.charAt(0);a in s.node.edges?o=s.node.edges[a]:(o=new e.TokenSet,s.node.edges[a]=o),1==s.str.length&&(o["final"]=!0),n.push({node:o,editsRemaining:s.editsRemaining,str:s.str.slice(1)})}if(0!=s.editsRemaining){if("*"in s.node.edges)var u=s.node.edges["*"];else{var u=new e.TokenSet;s.node.edges["*"]=u}if(0==s.str.length&&(u["final"]=!0),n.push({node:u,editsRemaining:s.editsRemaining-1,str:s.str}),s.str.length>1&&n.push({node:s.node,editsRemaining:s.editsRemaining-1,str:s.str.slice(1)}),1==s.str.length&&(s.node["final"]=!0),s.str.length>=1){if("*"in s.node.edges)var l=s.node.edges["*"];else{var l=new e.TokenSet;s.node.edges["*"]=l}1==s.str.length&&(l["final"]=!0),n.push({node:l,editsRemaining:s.editsRemaining-1,str:s.str.slice(1)})}if(s.str.length>1){var c,h=s.str.charAt(0),d=s.str.charAt(1);d in s.node.edges?c=s.node.edges[d]:(c=new e.TokenSet,s.node.edges[d]=c),1==s.str.length&&(c["final"]=!0),n.push({node:c,editsRemaining:s.editsRemaining-1,str:h+s.str.slice(2)})}}}return i},e.TokenSet.fromString=function(t){for(var r=new e.TokenSet,i=r,n=0,s=t.length;n=e;t--){var r=this.uncheckedNodes[t],i=r.child.toString();i in this.minimizedNodes?r.parent.edges[r["char"]]=this.minimizedNodes[i]:(r.child._str=i,this.minimizedNodes[i]=r.child),this.uncheckedNodes.pop()}},e.Index=function(e){this.invertedIndex=e.invertedIndex,this.fieldVectors=e.fieldVectors,this.tokenSet=e.tokenSet,this.fields=e.fields,this.pipeline=e.pipeline},e.Index.prototype.search=function(t){return this.query(function(r){var i=new e.QueryParser(t,r);i.parse()})},e.Index.prototype.query=function(t){for(var r=new e.Query(this.fields),i=Object.create(null),n=Object.create(null),s=Object.create(null),o=Object.create(null),a=Object.create(null),u=0;u1?this._b=1:this._b=e},e.Builder.prototype.k1=function(e){this._k1=e},e.Builder.prototype.add=function(t,r){var i=t[this._ref],n=Object.keys(this._fields);this._documents[i]=r||{},this.documentCount+=1;for(var s=0;s=this.length)return e.QueryLexer.EOS;var t=this.str.charAt(this.pos);return this.pos+=1,t},e.QueryLexer.prototype.width=function(){return this.pos-this.start},e.QueryLexer.prototype.ignore=function(){this.start==this.pos&&(this.pos+=1),this.start=this.pos},e.QueryLexer.prototype.backup=function(){this.pos-=1},e.QueryLexer.prototype.acceptDigitRun=function(){var t,r;do t=this.next(),r=t.charCodeAt(0);while(r>47&&r<58);t!=e.QueryLexer.EOS&&this.backup()},e.QueryLexer.prototype.more=function(){return this.pos1&&(t.backup(),t.emit(e.QueryLexer.TERM)),t.ignore(),t.more())return e.QueryLexer.lexText},e.QueryLexer.lexEditDistance=function(t){return t.ignore(),t.acceptDigitRun(),t.emit(e.QueryLexer.EDIT_DISTANCE),e.QueryLexer.lexText},e.QueryLexer.lexBoost=function(t){return t.ignore(),t.acceptDigitRun(),t.emit(e.QueryLexer.BOOST),e.QueryLexer.lexText},e.QueryLexer.lexEOS=function(t){t.width()>0&&t.emit(e.QueryLexer.TERM)},e.QueryLexer.termSeparator=e.tokenizer.separator,e.QueryLexer.lexText=function(t){for(;;){var r=t.next();if(r==e.QueryLexer.EOS)return e.QueryLexer.lexEOS;if(92!=r.charCodeAt(0)){if(":"==r)return e.QueryLexer.lexField;if("~"==r)return t.backup(),t.width()>0&&t.emit(e.QueryLexer.TERM),e.QueryLexer.lexEditDistance;if("^"==r)return t.backup(),t.width()>0&&t.emit(e.QueryLexer.TERM),e.QueryLexer.lexBoost;if("+"==r&&1===t.width())return t.emit(e.QueryLexer.PRESENCE),e.QueryLexer.lexText;if("-"==r&&1===t.width())return t.emit(e.QueryLexer.PRESENCE),e.QueryLexer.lexText;if(r.match(e.QueryLexer.termSeparator))return e.QueryLexer.lexTerm}else t.escapeCharacter()}},e.QueryParser=function(t,r){this.lexer=new e.QueryLexer(t),this.query=r,this.currentClause={},this.lexemeIdx=0},e.QueryParser.prototype.parse=function(){this.lexer.run(),this.lexemes=this.lexer.lexemes;for(var t=e.QueryParser.parseClause;t;)t=t(this);return this.query},e.QueryParser.prototype.peekLexeme=function(){return this.lexemes[this.lexemeIdx]},e.QueryParser.prototype.consumeLexeme=function(){var e=this.peekLexeme();return this.lexemeIdx+=1,e},e.QueryParser.prototype.nextClause=function(){var e=this.currentClause;this.query.clause(e),this.currentClause={}},e.QueryParser.parseClause=function(t){var r=t.peekLexeme();if(void 0!=r)switch(r.type){case e.QueryLexer.PRESENCE:return e.QueryParser.parsePresence;case e.QueryLexer.FIELD:return e.QueryParser.parseField;case e.QueryLexer.TERM:return e.QueryParser.parseTerm;default:var i="expected either a field or a term, found "+r.type;throw r.str.length>=1&&(i+=" with value '"+r.str+"'"),new e.QueryParseError(i,r.start,r.end)}},e.QueryParser.parsePresence=function(t){var r=t.consumeLexeme();if(void 0!=r){switch(r.str){case"-":t.currentClause.presence=e.Query.presence.PROHIBITED;break;case"+":t.currentClause.presence=e.Query.presence.REQUIRED;break;default:var i="unrecognised presence operator'"+r.str+"'";throw new e.QueryParseError(i,r.start,r.end)}var n=t.peekLexeme();if(void 0==n){var i="expecting term or field, found nothing";throw new e.QueryParseError(i,r.start,r.end)}switch(n.type){case e.QueryLexer.FIELD:return e.QueryParser.parseField;case e.QueryLexer.TERM:return e.QueryParser.parseTerm;default:var i="expecting term or field, found '"+n.type+"'";throw new e.QueryParseError(i,n.start,n.end)}}},e.QueryParser.parseField=function(t){var r=t.consumeLexeme();if(void 0!=r){if(t.query.allFields.indexOf(r.str)==-1){var i=t.query.allFields.map(function(e){return"'"+e+"'"}).join(", "),n="unrecognised field '"+r.str+"', possible fields: "+i;throw new e.QueryParseError(n,r.start,r.end)}t.currentClause.fields=[r.str];var s=t.peekLexeme();if(void 0==s){var n="expecting term, found nothing";throw new e.QueryParseError(n,r.start,r.end)}switch(s.type){case e.QueryLexer.TERM:return e.QueryParser.parseTerm;default:var n="expecting term, found '"+s.type+"'";throw new e.QueryParseError(n,s.start,s.end)}}},e.QueryParser.parseTerm=function(t){var r=t.consumeLexeme();if(void 0!=r){t.currentClause.term=r.str.toLowerCase(),r.str.indexOf("*")!=-1&&(t.currentClause.usePipeline=!1);var i=t.peekLexeme();if(void 0==i)return void t.nextClause();switch(i.type){case e.QueryLexer.TERM:return t.nextClause(),e.QueryParser.parseTerm;case e.QueryLexer.FIELD:return t.nextClause(),e.QueryParser.parseField;case e.QueryLexer.EDIT_DISTANCE:return e.QueryParser.parseEditDistance;case e.QueryLexer.BOOST:return e.QueryParser.parseBoost;case e.QueryLexer.PRESENCE:return t.nextClause(),e.QueryParser.parsePresence;default:var n="Unexpected lexeme type '"+i.type+"'";throw new e.QueryParseError(n,i.start,i.end)}}},e.QueryParser.parseEditDistance=function(t){var r=t.consumeLexeme();if(void 0!=r){var i=parseInt(r.str,10);if(isNaN(i)){var n="edit distance must be numeric";throw new e.QueryParseError(n,r.start,r.end)}t.currentClause.editDistance=i;var s=t.peekLexeme();if(void 0==s)return void t.nextClause();switch(s.type){case e.QueryLexer.TERM:return t.nextClause(),e.QueryParser.parseTerm;case e.QueryLexer.FIELD:return t.nextClause(),e.QueryParser.parseField;case e.QueryLexer.EDIT_DISTANCE:return e.QueryParser.parseEditDistance;case e.QueryLexer.BOOST:return e.QueryParser.parseBoost;case e.QueryLexer.PRESENCE:return t.nextClause(),e.QueryParser.parsePresence;default:var n="Unexpected lexeme type '"+s.type+"'";throw new e.QueryParseError(n,s.start,s.end)}}},e.QueryParser.parseBoost=function(t){var r=t.consumeLexeme();if(void 0!=r){var i=parseInt(r.str,10);if(isNaN(i)){var n="boost must be numeric";throw new e.QueryParseError(n,r.start,r.end)}t.currentClause.boost=i;var s=t.peekLexeme();if(void 0==s)return void t.nextClause();switch(s.type){case e.QueryLexer.TERM:return t.nextClause(),e.QueryParser.parseTerm;case e.QueryLexer.FIELD:return t.nextClause(),e.QueryParser.parseField;case e.QueryLexer.EDIT_DISTANCE:return e.QueryParser.parseEditDistance;case e.QueryLexer.BOOST:return e.QueryParser.parseBoost;case e.QueryLexer.PRESENCE:return t.nextClause(),e.QueryParser.parsePresence;default:var n="Unexpected lexeme type '"+s.type+"'";throw new e.QueryParseError(n,s.start,s.end)}}},function(e,t){"function"==typeof define&&define.amd?define(t):"object"==typeof exports?module.exports=t():e.lunr=t()}(this,function(){return e})}(); diff --git a/docs/assets/js/versions.js b/docs/assets/js/versions.js deleted file mode 100644 index 70658801a..000000000 --- a/docs/assets/js/versions.js +++ /dev/null @@ -1,20 +0,0 @@ -async function getVersions(lang) { - response = await fetch('/firefly/assets/js/versions.json'); - versions = await response.json(); - - versionDropdown = document.getElementById('versionDropdown'); - - versions.forEach(version => { - versionLink = document.createElement('a'); - url = '/firefly/'; - if (version != 'latest') { - url += version + '/' ; - } - if (lang != null && lang != '' && lang != 'en') { - url += lang + '/'; - } - versionLink.href = url; - versionLink.innerText = version; - versionDropdown.appendChild(versionLink) - }); -} \ No newline at end of file diff --git a/docs/assets/js/versions.json b/docs/assets/js/versions.json deleted file mode 100644 index c24f3d37c..000000000 --- a/docs/assets/js/versions.json +++ /dev/null @@ -1,3 +0,0 @@ -[ - "latest" -] diff --git a/docs/assets/js/zzzz-search-data.json b/docs/assets/js/zzzz-search-data.json deleted file mode 100644 index 6235244d3..000000000 --- a/docs/assets/js/zzzz-search-data.json +++ /dev/null @@ -1,72 +0,0 @@ ---- -permalink: /assets/js/search-data.json ---- -{ -{%- assign i = 0 -%} -{%- assign pages_array = '' | split: '' -%} -{%- assign pages_array = pages_array | push: site.html_pages -%} -{%- if site.just_the_docs.collections -%} - {%- for collection_entry in site.just_the_docs.collections -%} - {%- assign collection_key = collection_entry[0] -%} - {%- assign collection_value = collection_entry[1] -%} - {%- assign collection = site[collection_key] -%} - {%- if collection_value.search_exclude != true -%} - {%- assign pages_array = pages_array | push: collection -%} - {%- endif -%} - {%- endfor -%} -{%- endif -%} -{%- for pages in pages_array -%} - {%- for page in pages -%} - {%- if page.title and page.search_exclude != true -%} - {%- assign page_content = page.content -%} - {%- assign heading_level = site.search.heading_level | default: 2 -%} - {%- for j in (2..heading_level) -%} - {%- assign tag = '' -%} - {%- assign title = titleAndContent[0] | replace_first: '>', '

' | split: '

' -%} - {%- assign title = title[1] | strip_html -%} - {%- assign content = titleAndContent[1] -%} - {%- assign url = page.url -%} - {%- if title == page.title and parts[0] == '' -%} - {%- assign title_found = true -%} - {%- else -%} - {%- assign id = titleAndContent[0] -%} - {%- assign id = id | split: 'id="' -%} - {%- if id.size == 2 -%} - {%- assign id = id[1] -%} - {%- assign id = id | split: '"' -%} - {%- assign id = id[0] -%} - {%- capture url -%}{{ url | append: '#' | append: id }}{%- endcapture -%} - {%- endif -%} - {%- endif -%} - {%- unless i == 0 -%},{%- endunless -%} - "{{ i }}": { - "doc": {{ page.title | jsonify }}, - "title": {{ title | jsonify }}, - "content": {{ content | replace: ' **NOTE:** From the [macOS Catalina 10.15 Release Notes](https://developer.apple.com/documentation/macos-release-notes/macos-catalina-10_15-release-notes): Scripting language runtimes such as Python, Ruby, and Perl are included in macOS for compatibility with legacy software. Future versions of macOS won’t include scripting language runtimes by default, and might require you to install additional packages. If your software depends on scripting languages, it’s recommended that you bundle the runtime within the app. (49764202) - -If you're using an Apple Silicon based Mac, the version of Ruby that comes with macOS supports both Intel and ARM binaries which unfortunately ends up causing some problems when installing certain gems. We recommend installing Ruby with `brew` and setting it on your path. This will also give you a newer version of Ruby. To do this, run: - -``` -brew install ruby -echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc -``` - -### Linux -You will need to install `ruby` and `bundle` and have them on your path to build and serve the docs locally. On Ubuntu, to install these, run the following commands: - -``` -sudo apt-get update -sudo apt-get install ruby ruby-bundler -``` - -## Build and serve the docs locally -To build and serve the docs locally, from the project root, navigate to the docs directory: - -``` -cd docs -``` - -Install docs dependencies: - -``` -bundle install -``` - -And start the Jekyll test server: - -``` -bundle exec jekyll serve --livereload -``` - -You should now be able to open http://127.0.0.1:4000/firefly/index.html in your browser and see a locally hosted version of the doc site. - -As you make changes to files in the `./docs` directory, Jekyll will automatically rebuild the pages, and notify you of any errors or warnings in your terminal. If you have a browser open, it will automatically reload when changes are made to pages. diff --git a/docs/firefly_logo.png b/docs/firefly_logo.png deleted file mode 100644 index 63134e2b2..000000000 Binary files a/docs/firefly_logo.png and /dev/null differ diff --git a/docs/firefly_logo_36h.png b/docs/firefly_logo_36h.png deleted file mode 100644 index fbe8ab148..000000000 Binary files a/docs/firefly_logo_36h.png and /dev/null differ diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 68527df5a..000000000 --- a/docs/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -layout: i18n_page -title: pages.home -nav_order: 1 ---- - -{% tf index.md %} - diff --git a/docs/overview/index.md b/docs/overview/index.md deleted file mode 100644 index 546c5b3ec..000000000 --- a/docs/overview/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -layout: i18n_page -title: pages.understanding_firefly -nav_order: 2 -has_children: true ---- - -# Understanding FireFly diff --git a/docs/overview/key_features.md b/docs/overview/key_features.md deleted file mode 100644 index 914188dc0..000000000 --- a/docs/overview/key_features.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -layout: i18n_page -title: pages.key_features -parent: pages.understanding_firefly -nav_order: 3 -has_children: true ---- - -# Key Features -{: .no_toc } - ---- -![Hyperledger FireFly features](../images/firefly_functionality_overview.png) - -Hyperledger FireFly provides a rich suite of features for building new applications, and connecting -existing Web3 ecosystems to your business. In this section we introduce each core pillar of functionality. - - diff --git a/docs/reference/blockchain_operation_errors.md b/docs/reference/blockchain_operation_errors.md deleted file mode 100644 index 4dd7c8c84..000000000 --- a/docs/reference/blockchain_operation_errors.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -layout: default -title: Blockchain Operation Errors -parent: pages.reference -nav_order: 6 ---- - -# Blockchain Operation Errors -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- - -## Blockchain error messages - -The receipt for a FireFly blockchain operation contains an `extraInfo` section that records additional information about the transaction. For example: - -``` -"receipt": { - ... - "extraInfo": [ - { - { - "contractAddress":"0x87ae94ab290932c4e6269648bb47c86978af4436", - "cumulativeGasUsed":"33812", - "from":"0x2b1c769ef5ad304a4889f2a07a6617cd935849ae", - "to":"0x302259069aaa5b10dc6f29a9a3f72a8e52837cc3", - "gasUsed":"33812", - "status":"0", - "errorMessage":"Not enough tokens", - } - } - ], - ... -}, -``` - -The `errorMessage` field can be be set by a blockchain connector to provide FireFly and the end-user with more information about the reason why a tranasction failed. The blockchain connector can choose what information to include in `errorMessage` field. It may be set to an error message relating to the blockchain connector itself or an error message passed back from the blockchain or smart contract that was invoked. - -## Default error format with Hyperledger FireFly 1.3 and Hyperledger Besu 24.3.0 - -If FireFly is configured to connect to a Besu EVM client, and Besu has been configured with the `revert-reason-enabled=true` setting (note - the default value for Besu is `false`) error messages passed to FireFly from the blockchain client itself will be set correctly in the FireFly blockchain operation. For example: - - - `"errorMessage":"Not enough tokens"` for a revert error string from a smart contract - -If the smart contract uses a custom error type, Besu will return the revert reason to FireFly as a hexadecimal string but FireFly will be unable to decode it into. In this case the blockchain operation error message and return values will be set to: - - - `"errorMessage":"FF23053: Error return value for custom error: ` - - `"returnValue":""` - -A future update to FireFly could be made to automatically decode custom error revert reasons if FireFly knows the ABI for the custom error. See [FireFly issue 1466](https://github.com/hyperledger/firefly/issues/1466) which describes the current limitation. - -If FireFly is configured to connect to Besu without `revert-reason-enabled=true` the error message will be set to: - - - `"errorMessage":"FF23054: Error return value unavailable"` - -## Error retrieval details - -The precise format of the error message in a blockchain operation can vary based on different factors. The sections below describe in detail how the error message is populted, with specific references to the `firefly-evmconnect` blockchain connector. - -### Format of a `firefly-evmconnect` error message - -The following section describes the way that the `firefly-evmconnect` plugin uses the `errorMessage` field. This serves both as an explanation of how EVM-based transaction errors will be formatted, and as a guide that other blockchain connectors may decide to follow. - -The `errorMessage` field for a `firefly-evmconnect` transaction may contain one of the following: - -1. An error message from the FireFly blockchain connector - - For example `"FF23054: Error return value unavailable"` -2. A decoded error string from the blockchain transaction - - For example `Not enough tokens` - - This could be an error string from a smart contract e.g. `require(requestedTokens <= allowance, "Not enough tokens");` -3. An un-decoded byte string from the blockchain transaction - - For example -``` -FF23053: Error return value for custom error: 0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010 -``` - - This could be a custom error from a smart contract e.g. -``` -error AllowanceTooSmall(uint256 requested, uint256 allowance); -... -revert AllowanceTooSmall({ requested: 100, allowance: 20 }); -``` - - If an error reason cannot be decoded the `returnValue` of the `extraInfo` will be set to the raw byte string. For example: -``` -"receipt": { - ... - "extraInfo": [ - { - { - "contractAddress":"0x87ae94ab290932c4e6269648bb47c86978af4436", - "cumulativeGasUsed":"33812", - "from":"0x2b1c769ef5ad304a4889f2a07a6617cd935849ae", - "to":"0x302259069aaa5b10dc6f29a9a3f72a8e52837cc3", - "gasUsed":"33812", - "status":"0", - "errorMessage":"FF23053: Error return value for custom error: 0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010", - "returnValue":"0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010" - } - } - ], - ... -}, -``` - -### Retrieving EVM blockchain transaction errors - -The ability of a blockchain connector such as `firefly-evmconnect` to retrieve the reason for a transaction failure, is dependent on by the configuration of the blockchain it is connected to. For an EVM blockchain the reason why a transaction failed is recorded with the `REVERT` op code, with a `REASON` set to the reason for the failure. By default, most EVM clients do not store this reason in the transaction receipt. This is typically to reduce resource consumption such as memory usage in the client. It is usually possible to configure an EVM client to store the revert reason in the transaction receipt. For example Hyperledger Besuβ„’ provides the `--revert-reason-enabled` configuration option. If the transaction receipt does not contain the revert reason it is possible to request that an EVM client re-run the transaction and return a trace of all of the op-codes, including the final `REVERT` `REASON`. This can be a resource intensive request to submit to an EVM client, and is only available on archive nodes or for very recent blocks. - -The `firefly-evmconnect` blockchain connector attempts to obtain the reason for a transaction revert and include it in the `extraInfo` field. It uses the following mechanisms, in this order: - -1. Checks if the blockchain transaction receipt contains the revert reason. -2. If the revert reason is not in the receipt, and the `connector.traceTXForRevertReason` configuration option is set to `true`, calls `debug_traceTransaction` to obtain a full trace of the transaction and extract the revert reason. By default, `connector.traceTXForRevertReason` is set to `false` to avoid submitting high-resource requests to the EVM client. - -If the revert reason can be obtained using either mechanism above, the revert reason bytes are decoded in the following way: - - Attempts to decode the bytes as the standard `Error(string)` signature format and includes the decoded string in the `errorMessage` - - If the reason is not a standard `Error(String)` error, sets the `errorMessage` to `FF23053: Error return value for custom error: ` and includes the raw byte string in the `returnValue` field. - diff --git a/docs/reference/index.md b/docs/reference/index.md deleted file mode 100644 index 51ba6fc4c..000000000 --- a/docs/reference/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -layout: i18n_page -title: pages.reference -nav_order: 5 -has_children: true ---- - -# Reference - ---- - -This section contains detailed reference information for developers using FireFly. \ No newline at end of file diff --git a/docs/reference/microservices/index.md b/docs/reference/microservices/index.md deleted file mode 100644 index fc2312715..000000000 --- a/docs/reference/microservices/index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: default -title: Microservices -parent: pages.reference -nav_order: 11 -has_children: true ---- diff --git a/docs/reference/types/_includes/ffi_description.md b/docs/reference/types/_includes/ffi_description.md deleted file mode 100644 index c1b09e96f..000000000 --- a/docs/reference/types/_includes/ffi_description.md +++ /dev/null @@ -1 +0,0 @@ -See [FireFly Interface Format](../firefly_interface_format) \ No newline at end of file diff --git a/docs/reference/types/dataref.md b/docs/reference/types/dataref.md deleted file mode 100644 index af12761ad..000000000 --- a/docs/reference/types/dataref.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -layout: default -title: DataRef -parent: Types -grand_parent: pages.reference -nav_order: 4 ---- - -# DataRef -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## DataRef - -### Example - -```json -{ - "id": "5bea782a-6cf2-4e01-95ee-cb5fa05873e9", - "hash": "8b7df143d91c716ecfa5fc1730022f6b421b05cedee8fd52b1fc65a96030ad52" -} -``` - -### Field Descriptions - -| Field Name | Description | Type | -|------------|-------------|------| -| id | The UUID of the referenced data resource | `UUID` | -| hash | The hash of the referenced data | `Bytes32` | - diff --git a/docs/reference/types/index.md b/docs/reference/types/index.md deleted file mode 100644 index b72923a75..000000000 --- a/docs/reference/types/index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: default -title: Core Resources -parent: pages.reference -nav_order: 1 -has_children: true ---- diff --git a/docs/reference/types/simpletypes.md b/docs/reference/types/simpletypes.md deleted file mode 100644 index 981742e63..000000000 --- a/docs/reference/types/simpletypes.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -layout: default -title: Simple Types -parent: Core Resources -grand_parent: pages.reference -nav_order: 1 ---- - -# Simple Types -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -## UUID - -{% include_relative _includes/uuid_description.md %} - -## FFTime - -{% include_relative _includes/fftime_description.md %} - -## FFBigInt - -{% include_relative _includes/ffbigint_description.md %} - -## JSONAny - -{% include_relative _includes/jsonany_description.md %} - -## JSONObject - -{% include_relative _includes/jsonobject_description.md %} - diff --git a/docs/tutorials/chains/index.md b/docs/tutorials/chains/index.md deleted file mode 100644 index c94039e11..000000000 --- a/docs/tutorials/chains/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -layout: i18n_page -title: pages.chains -parent: pages.tutorials -nav_order: 9 -has_children: true ---- - -# {% t pages.chains %} - -If you want to connect a local development environment, created with the FireFly CLI to another chain, there are several tutorials below to help you do that. These other chains could also be on the same machine as FireFly, or they could be somewhere on the public internet, depending on the tutorial. \ No newline at end of file diff --git a/docs/tutorials/custom_contracts/tezos.md b/docs/tutorials/custom_contracts/tezos.md deleted file mode 100644 index 9289b6ba2..000000000 --- a/docs/tutorials/custom_contracts/tezos.md +++ /dev/null @@ -1,1044 +0,0 @@ ---- -layout: default -title: Tezos -parent: pages.custom_smart_contracts -grand_parent: pages.tutorials -nav_order: 3 ---- - -# Work with Tezos smart contracts - -{: .no_toc } -This guide describes the steps to deploy a smart contract to a Tezos blockchain and use FireFly to interact with it in order to submit transactions, query for states and listening for events. - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- - -## Smart Contract Languages - -Smart contracts on Tezos can be programmed using familiar, developer-friendly languages. All features available on Tezos can be written in any of the high-level languages used to write smart contracts, such as Archetype, LIGO, and SmartPy. These languages all compile down to [Michelson](https://tezos.gitlab.io/active/michelson.html) and you can switch between languages based on your preferences and projects. - -> **NOTE:** For this tutorial we are going to use [SmartPy](https://smartpy.io/) for building Tezos smart contracts utilizing the broadly adopted Python language. - -## Example smart contract - -First let's look at a simple contract smart contract called `SimpleStorage`, which we will be using on a Tezos blockchain. Here we have one state variable called 'storedValue' and initialized with the value 12. During initialization the type of the variable was defined as 'int'. You can see more at [SmartPy types](https://smartpy.io/manual/syntax/integers-and-mutez). And then we added a simple test, which set the storage value to 15 and checks that the value was changed as expected. - -> **NOTE:** Smart contract's tests (marked with `@sp.add_test` annotation) are used to verify the validity of contract entrypoints and do not affect the state of the contract during deployment. - -Here is the source for this contract: - -```smarty -import smartpy as sp - -@sp.module -def main(): - # Declares a new contract - class SimpleStorage(sp.Contract): - # Storage. Persists in between transactions - def __init__(self, value): - self.data.x = value - - # Allows the stored integer to be changed - @sp.entrypoint - def set(self, params): - self.data.x = params.value - - # Returns the currently stored integer - @sp.onchain_view() - def get(self): - return self.data.x - -@sp.add_test() -def test(): - # Create a test scenario - scenario = sp.test_scenario("Test simple storage", main) - scenario.h1("SimpleStorage") - - # Initialize the contract - c = main.SimpleStorage(12) - - # Run some test cases - scenario += c - c.set(value=15) - scenario.verify(c.data.x == 15) - scenario.verify(scenario.compute(c.get()) == 15) -``` - -## Contract deployment via SmartPy IDE - -To deploy the contract, we will use [SmartPy IDE](https://smartpy.io/ide). -1. Open an IDE; -2. Paste the contract code; -3. Click "Run code" button; -4. Then you will see "Show Michelson" button, click on that; -5. On the opened pop-up click button "Deploy Contract"; -6. Choose the Ghostnet network; -7. Select an account, which you're going to use to deploy the contract; -8. Click "Estimate Cost From RPC" button; -9. Click "Deploy Contract" button; - -![ContractDeployment](images/tezos_contract_deployment.png) -![ContractDeployment2](images/tezos_contract_deployment2.png) -![ContractDeployment3](images/tezos_contract_deployment3.png) - -Here we can see that our new contract address is `KT1ED4gj2xZnp8318yxa5NpvyvW15pqe4yFg`. This is the address that we will reference in the rest of this guide. - -## Contract deployment via HTTP API - -To deploy the contract we can use HTTP API: -`POST` `http://localhost:5000/api/v1/namespaces/default/contracts/deploy` - -```json -{ - "contract": { - "code": [ - { - "prim": "storage", - "args": [ - { - "prim": "int" - } - ] - }, - { - "prim": "parameter", - "args": [ - { - "prim": "int", - "annots": [ - "%set" - ] - } - ] - }, - { - "prim": "code", - "args": [ - [ - { - "prim": "CAR" - }, - { - "prim": "NIL", - "args": [ - { - "prim": "operation" - } - ] - }, - { - "prim": "PAIR" - } - ] - ] - }, - { - "prim": "view", - "args": [ - { - "string": "get" - }, - { - "prim": "unit" - }, - { - "prim": "int" - }, - [ - { - "prim": "CDR" - } - ] - ] - } - ], - "storage": { - "int": "12" - } - } -} -``` - -The `contract` field has two fields - `code` with Michelson code of contract and `storage` with initial Storage values. - -The response of request above: - -``` json -{ - "id": "0c3810c7-baed-4077-9d2c-af316a4a567f", - "namespace": "default", - "tx": "21d03e6d-d106-48f4-aacd-688bf17b71fd", - "type": "blockchain_deploy", - "status": "Pending", - "plugin": "tezos", - "input": { - "contract": { - "code": [ - { - "args": [ - { - "prim": "int" - } - ], - "prim": "storage" - }, - { - "args": [ - { - "annots": [ - "%set" - ], - "prim": "int" - } - ], - "prim": "parameter" - }, - { - "args": [ - [ - { - "prim": "CAR" - }, - { - "args": [ - { - "prim": "operation" - } - ], - "prim": "NIL" - }, - { - "prim": "PAIR" - } - ] - ], - "prim": "code" - }, - { - "args": [ - { - "string": "get" - }, - { - "prim": "unit" - }, - { - "prim": "int" - }, - [ - { - "prim": "CDR" - } - ] - ], - "prim": "view" - } - ], - "storage": { - "int": "12" - } - }, - "definition": null, - "input": null, - "key": "tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31", - "options": null - }, - "created": "2024-04-01T14:20:20.665039Z", - "updated": "2024-04-01T14:20:20.665039Z" -} -``` - -The success result of deploy can be checked by -`GET` `http://localhost:5000/api/v1/namespaces/default/operations/0c3810c7-baed-4077-9d2c-af316a4a567f` -where `0c3810c7-baed-4077-9d2c-af316a4a567f` is operation id from response above. - -The success response: - -``` json -{ - "id": "0c3810c7-baed-4077-9d2c-af316a4a567f", - "namespace": "default", - "tx": "21d03e6d-d106-48f4-aacd-688bf17b71fd", - "type": "blockchain_deploy", - "status": "Succeeded", - "plugin": "tezos", - "input": { - "contract": { - "code": [ - { - "args": [ - { - "prim": "int" - } - ], - "prim": "storage" - }, - { - "args": [ - { - "annots": [ - "%set" - ], - "prim": "int" - } - ], - "prim": "parameter" - }, - { - "args": [ - [ - { - "prim": "CAR" - }, - { - "args": [ - { - "prim": "operation" - } - ], - "prim": "NIL" - }, - { - "prim": "PAIR" - } - ] - ], - "prim": "code" - }, - { - "args": [ - { - "string": "get" - }, - { - "prim": "unit" - }, - { - "prim": "int" - }, - [ - { - "prim": "CDR" - } - ] - ], - "prim": "view" - } - ], - "storage": { - "int": "12" - } - }, - "definition": null, - "input": null, - "key": "tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31", - "options": null - }, - "output": { - "headers": { - "requestId": "default:0c3810c7-baed-4077-9d2c-af316a4a567f", - "type": "TransactionSuccess" - }, - "protocolId": "ProxfordYmVfjWnRcgjWH36fW6PArwqykTFzotUxRs6gmTcZDuH", - "transactionHash": "ootDut4xxR2yeYz6JuySuyTVZnXgda2t8SYrk3iuJpm531TZuCj" - }, - "created": "2024-04-01T14:20:20.665039Z", - "updated": "2024-04-01T14:20:20.665039Z", - "detail": { - "created": "2024-04-01T14:20:21.928976Z", - "firstSubmit": "2024-04-01T14:20:22.714493Z", - "from": "tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31", - "gasPrice": "0", - "historySummary": [ - { - "count": 1, - "firstOccurrence": "2024-04-01T14:20:21.930764Z", - "lastOccurrence": "2024-04-01T14:20:21.930765Z", - "subStatus": "Received" - }, - { - "action": "AssignNonce", - "count": 2, - "firstOccurrence": "2024-04-01T14:20:21.930767Z", - "lastOccurrence": "2024-04-01T14:20:22.714772Z" - }, - { - "action": "RetrieveGasPrice", - "count": 1, - "firstOccurrence": "2024-04-01T14:20:22.714774Z", - "lastOccurrence": "2024-04-01T14:20:22.714774Z" - }, - { - "action": "SubmitTransaction", - "count": 1, - "firstOccurrence": "2024-04-01T14:20:22.715269Z", - "lastOccurrence": "2024-04-01T14:20:22.715269Z" - }, - { - "action": "ReceiveReceipt", - "count": 1, - "firstOccurrence": "2024-04-01T14:20:29.244396Z", - "lastOccurrence": "2024-04-01T14:20:29.244396Z" - }, - { - "action": "Confirm", - "count": 1, - "firstOccurrence": "2024-04-01T14:20:29.244762Z", - "lastOccurrence": "2024-04-01T14:20:29.244762Z" - } - ], - "id": "default:0c3810c7-baed-4077-9d2c-af316a4a567f", - "lastSubmit": "2024-04-01T14:20:22.714493Z", - "nonce": "23094946", - "policyInfo": {}, - "receipt": { - "blockHash": "BLvWL4t8GbaufGcQwiv3hHCsvgD6qwXfAXofyvojSMoFeGMXMR1", - "blockNumber": "5868268", - "contractLocation": { - "address": "KT1CkTPsgTUQxR3CCpvtrcuQFV5Jf7cJgHFg" - }, - "extraInfo": [ - { - "consumedGas": "584", - "contractAddress": "KT1CkTPsgTUQxR3CCpvtrcuQFV5Jf7cJgHFg", - "counter": null, - "errorMessage": null, - "fee": null, - "from": null, - "gasLimit": null, - "paidStorageSizeDiff": "75", - "status": "applied", - "storage": null, - "storageLimit": null, - "storageSize": "75", - "to": null - } - ], - "protocolId": "ProxfordYmVfjWnRcgjWH36fW6PArwqykTFzotUxRs6gmTcZDuH", - "success": true, - "transactionIndex": "0" - }, - "sequenceId": "018e9a08-582a-01ec-9209-9d79ef742c9b", - "status": "Succeeded", - "transactionData": "c37274b662d68da8fdae2a02ad6c460a79933c70c6fa7500dc98a9ade6822f026d00673bb6e6298063f97940953de23d441ab20bf757f602a3cd810bad05b003000000000041020000003c0500045b00000004257365740501035b050202000000080316053d036d03420991000000130100000003676574036c035b020000000203170000000000000002000c", - "transactionHash": "ootDut4xxR2yeYz6JuySuyTVZnXgda2t8SYrk3iuJpm531TZuCj", - "transactionHeaders": { - "from": "tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31", - "nonce": "23094946" - }, - "updated": "2024-04-01T14:20:29.245172Z" - } -} -``` - -## The FireFly Interface Format - -As we know from the previous section - smart contracts on the Tezos blockchain are using the domain-specific, stack-based programming language called [Michelson](https://tezos.gitlab.io/active/michelson.html). It is a key component of the Tezos platform and plays a fundamental role in defining the behavior of smart contracts and facilitating their execution. -This language is very efficient but also a bit tricky and challenging for learning, so in order to teach FireFly how to interact with the smart contract, we will be using [FireFly Interface (FFI)](../../reference/firefly_interface_format.md) to define the contract inteface which later will be encoded to Michelson. - -### Schema details - -The `details` field is used to encapsulate blockchain specific type information about a specific field. (More details at [schema details](../../reference/firefly_interface_format.md#schema-details)) - -#### Supported Tezos types - -- nat -- integer -- string -- address -- bytes -- boolean -- variant -- list -- struct -- map - -#### Internal type vs Internal schema - -internalType is a field which is used to describe tezos primitive types - -``` json -{ - "details": { - "type": "address", - "internalType": "address" - } -} -``` - -internalSchema in turn is used to describe more complex tezos types as list, struct or variant - -Struct example: - -``` json -{ - "details": { - "type": "schema", - "internalSchema": { - "type": "struct", - "args": [ - { - "name": "metadata", - "type": "bytes" - }, - { - "name": "token_id", - "type": "nat" - } - ] - } - } -} -``` - -List example: - -``` json -{ - "details": { - "type": "schema", - "internalSchema": { - "type": "struct", - "args": [ - { - "name": "metadata", - "type": "bytes" - }, - { - "name": "token_id", - "type": "nat" - } - ] - } - } -} -``` - -Variant example: - -``` json -{ - "details": { - "type": "schema", - "internalSchema": { - "type": "variant", - "variants": [ - "add_operator", - "remove_operator" - ], - "args": [ - { - "type": "struct", - "args": [ - { - "name": "owner", - "type": "address" - }, - { - "name": "operator", - "type": "address" - }, - { - "name": "token_id", - "type": "nat" - } - ] - } - ] - } - } -} -``` - -Map example: - -``` json -{ - "details": { - "type": "schema", - "internalSchema": { - "type": "map", - "args": [ - { - "name": "key", - "type": "integer" - }, - { - "name": "value", - "type": "string" - } - ] - } - } -} -``` - -#### Options - -Option type is used to indicate a value as optional (see more at [smartpy options](https://smartpy.io/manual/syntax/options-and-variants#options)) - -``` json -{ - "details": { - "type": "string", - "internalType": "string", - "kind": "option" - } -} -``` - -### FA2 example - -The following FFI sample demonstrates the specification for the widely used FA2 (analogue of ERC721 for EVM) smart contract: - -```json -{ - "namespace": "default", - "name": "fa2", - "version": "v1.0.0", - "description": "", - "methods": [ - { - "name": "burn", - "pathname": "", - "description": "", - "params": [ - { - "name": "token_ids", - "schema": { - "type": "array", - "details": { - "type": "nat", - "internalType": "nat" - } - } - } - ], - "returns": [] - }, - { - "name": "destroy", - "pathname": "", - "description": "", - "params": [], - "returns": [] - }, - { - "name": "mint", - "pathname": "", - "description": "", - "params": [ - { - "name": "owner", - "schema": { - "type": "string", - "details": { - "type": "address", - "internalType": "address" - } - } - }, - { - "name": "requests", - "schema": { - "type": "array", - "details": { - "type": "schema", - "internalSchema": { - "type": "struct", - "args": [ - { - "name": "metadata", - "type": "bytes" - }, - { - "name": "token_id", - "type": "nat" - } - ] - } - } - } - } - ], - "returns": [] - }, - { - "name": "pause", - "pathname": "", - "description": "", - "params": [ - { - "name": "pause", - "schema": { - "type": "boolean", - "details": { - "type": "boolean", - "internalType": "boolean" - } - } - } - ], - "returns": [] - }, - { - "name": "select", - "pathname": "", - "description": "", - "params": [ - { - "name": "batch", - "schema": { - "type": "array", - "details": { - "type": "schema", - "internalSchema": { - "type": "struct", - "args": [ - { - "name": "token_id", - "type": "nat" - }, - { - "name": "recipient", - "type": "address" - }, - { - "name": "token_id_start", - "type": "nat" - }, - { - "name": "token_id_end", - "type": "nat" - } - ] - } - } - } - } - ], - "returns": [] - }, - { - "name": "transfer", - "pathname": "", - "description": "", - "params": [ - { - "name": "batch", - "schema": { - "type": "array", - "details": { - "type": "schema", - "internalSchema": { - "type": "struct", - "args": [ - { - "name": "from_", - "type": "address" - }, - { - "name": "txs", - "type": "list", - "args": [ - { - "type": "struct", - "args": [ - { - "name": "to_", - "type": "address" - }, - { - "name": "token_id", - "type": "nat" - }, - { - "name": "amount", - "type": "nat" - } - ] - } - ] - } - ] - } - } - } - } - ], - "returns": [] - }, - { - "name": "update_admin", - "pathname": "", - "description": "", - "params": [ - { - "name": "admin", - "schema": { - "type": "string", - "details": { - "type": "address", - "internalType": "address" - } - } - } - ], - "returns": [] - }, - { - "name": "update_operators", - "pathname": "", - "description": "", - "params": [ - { - "name": "requests", - "schema": { - "type": "array", - "details": { - "type": "schema", - "internalSchema": { - "type": "variant", - "variants": [ - "add_operator", - "remove_operator" - ], - "args": [ - { - "type": "struct", - "args": [ - { - "name": "owner", - "type": "address" - }, - { - "name": "operator", - "type": "address" - }, - { - "name": "token_id", - "type": "nat" - } - ] - } - ] - } - } - } - } - ], - "returns": [] - } - ], - "events": [] -} -``` - - -## Broadcast the contract interface - -Now that we have a FireFly Interface representation of our smart contract, we want to broadcast that to the entire network. This broadcast will be pinned to the blockchain, so we can always refer to this specific name and version, and everyone in the network will know exactly which contract interface we are talking about. - -We will use the FFI JSON constructed above and `POST` that to the `/contracts/interfaces` API endpoint. - -### Request - -`POST` `http://localhost:5000/api/v1/namespaces/default/contracts/interfaces` - -```json -{ - "namespace": "default", - "name": "simplestorage", - "version": "v1.0.0", - "description": "", - "methods": [ - { - "name": "set", - "pathname": "", - "description": "", - "params": [ - { - "name": "newValue", - "schema": { - "type": "integer", - "details": { - "type": "integer", - "internalType": "integer" - } - } - } - ], - "returns": [] - }, - { - "name": "get", - "pathname": "", - "description": "", - "params": [], - "returns": [] - } - ], - "events": [] -} -``` - -### Response - -```json -{ - "id": "f9e34787-e634-46cd-af47-b52c537404ff", - "namespace": "default", - "name": "simplestorage", - "description": "", - "version": "v1.0.0", - "methods": [ - { - "id": "78f13a7f-7b85-47c3-bf51-346a9858c027", - "interface": "f9e34787-e634-46cd-af47-b52c537404ff", - "name": "set", - "namespace": "default", - "pathname": "set", - "description": "", - "params": [ - { - "name": "newValue", - "schema": { - "type": "integer", - "details": { - "type": "integer", - "internalType": "integer" - } - } - } - ], - "returns": [] - }, - { - "id": "ee864e25-c3f7-42d3-aefd-a82f753e9002", - "interface": "f9e34787-e634-46cd-af47-b52c537404ff", - "name": "get", - "namespace": "tezos", - "pathname": "get", - "description": "", - "params": [], - "returns": [] - } - ] -} -``` - -> **NOTE**: We can broadcast this contract interface conveniently with the help of FireFly Sandbox running at `http://127.0.0.1:5108` -* Go to the `Contracts Section` -* Click on `Define a Contract Interface` -* Select `FFI - FireFly Interface` in the `Interface Fromat` dropdown -* Copy the `FFI JSON` crafted by you into the `Schema` Field -* Click on `Run` - -## Create an HTTP API for the contract - -Now comes the fun part where we see some of the powerful, developer-friendly features of FireFly. The next thing we're going to do is tell FireFly to build an HTTP API for this smart contract, complete with an OpenAPI Specification and Swagger UI. As part of this, we'll also tell FireFly where the contract is on the blockchain. - -Like the interface broadcast above, this will also generate a broadcast which will be pinned to the blockchain so all the members of the network will be aware of and able to interact with this API. - -We need to copy the `id` field we got in the response from the previous step to the `interface.id` field in the request body below. We will also pick a name that will be part of the URL for our HTTP API, so be sure to pick a name that is URL friendly. In this case we'll call it `simple-storage`. Lastly, in the `location.address` field, we're telling FireFly where an instance of the contract is deployed on-chain. - -> **NOTE**: The `location` field is optional here, but if it is omitted, it will be required in every request to invoke or query the contract. This can be useful if you have multiple instances of the same contract deployed to different addresses. - -### Request - -`POST` `http://localhost:5000/api/v1/namespaces/default/apis` - -```json -{ - "name": "simple-storage", - "interface": { - "id": "f9e34787-e634-46cd-af47-b52c537404ff" - }, - "location": { - "address": "KT1ED4gj2xZnp8318yxa5NpvyvW15pqe4yFg" - } -} -``` - -### Response - -```json -{ - "id": "af09de97-741d-4f61-8d30-4db5e7460f76", - "namespace": "default", - "interface": { - "id": "f9e34787-e634-46cd-af47-b52c537404ff" - }, - "location": { - "address": "KT1ED4gj2xZnp8318yxa5NpvyvW15pqe4yFg" - }, - "name": "simple-storage", - "urls": { - "openapi": "http://127.0.0.1:5000/api/v1/namespaces/default/apis/simple-storage/api/swagger.json", - "ui": "http://127.0.0.1:5000/api/v1/namespaces/default/apis/simple-storage/api" - } -} -``` - -## View OpenAPI spec for the contract - -You'll notice in the response body that there are a couple of URLs near the bottom. If you navigate to the one labeled `ui` in your browser, you should see the Swagger UI for your smart contract. - -![Swagger UI](images/simple_storage_swagger.png "Swagger UI") - -## Invoke the smart contract - -Now that we've got everything set up, it's time to use our smart contract! We're going to make a `POST` request to the `invoke/set` endpoint to set the integer value on-chain. Let's set it to the value of `3` right now. - -### Request - -`POST` `http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/invoke/set` - -```json -{ - "input": { - "newValue": 3 - } -} -``` - -### Response - -```json -{ - "id": "87c7ee1b-33d1-46e2-b3f5-8566c14367cf", - "type": "blockchain_invoke", - "status": "Pending", - "..." -} -``` - -You'll notice that we got an ID back with status `Pending`, and that's expected due to the asynchronous programming model of working with smart contracts in FireFly. To see what the value is now, we can query the smart contract. - -## Query the current value - -To make a read-only request to the blockchain to check the current value of the stored integer, we can make a `POST` to the `query/get` endpoint. - -### Request - -`POST` `http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/query/get` - -```json -{} -``` - -### Response - -```json -{ - "3" -} -``` - -> **NOTE:** Some contracts may have queries that require input parameters. That's why the query endpoint is a `POST`, rather than a `GET` so that parameters can be passed as JSON in the request body. This particular function does not have any parameters, so we just pass an empty JSON object. diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md deleted file mode 100644 index 877f2dd07..000000000 --- a/docs/tutorials/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -layout: i18n_page -title: pages.tutorials -nav_order: 4 -has_children: true ---- - -# Tutorials diff --git a/internal/apiserver/swagger_check_test.go b/internal/apiserver/swagger_check_test.go index 10e3dc67e..11de61d7a 100644 --- a/internal/apiserver/swagger_check_test.go +++ b/internal/apiserver/swagger_check_test.go @@ -62,7 +62,7 @@ func TestDiffSwaggerYAML(t *testing.T) { actualSwaggerHash.Write(b) var existingSwaggerBytes []byte - existingSwaggerBytes, err = os.ReadFile(filepath.Join("..", "..", "docs", "swagger", "swagger.yaml")) + existingSwaggerBytes, err = os.ReadFile(filepath.Join("..", "..", "doc-site", "docs", "swagger", "swagger.yaml")) assert.NoError(t, err) expectedSwaggerHash := sha1.New() diff --git a/internal/apiserver/swagger_generate_test.go b/internal/apiserver/swagger_generate_test.go index ce5171ecf..8d394960a 100644 --- a/internal/apiserver/swagger_generate_test.go +++ b/internal/apiserver/swagger_generate_test.go @@ -56,6 +56,6 @@ func TestDownloadSwaggerYAML(t *testing.T) { assert.NoError(t, err) err = doc.Validate(context.Background()) assert.NoError(t, err) - err = os.WriteFile(filepath.Join("..", "..", "docs", "swagger", "swagger.yaml"), b, 0644) + err = os.WriteFile(filepath.Join("..", "..", "doc-site", "docs", "swagger", "swagger.yaml"), b, 0644) assert.NoError(t, err) } diff --git a/internal/events/websockets/websockets_test.go b/internal/events/websockets/websockets_test.go index cba25ebfa..031adebdf 100644 --- a/internal/events/websockets/websockets_test.go +++ b/internal/events/websockets/websockets_test.go @@ -1219,4 +1219,4 @@ func TestHandleStartWrongNamespace(t *testing.T) { err := wc.handleStart(startMessage) assert.Error(t, err) assert.Regexp(t, "FF10462", err) -} +} \ No newline at end of file diff --git a/internal/reference/generate_reference_test.go b/internal/reference/generate_reference_test.go index 6a0966785..c65a23a35 100644 --- a/internal/reference/generate_reference_test.go +++ b/internal/reference/generate_reference_test.go @@ -39,7 +39,7 @@ func TestGenerateMarkdownPages(t *testing.T) { assert.NotNil(t, markdownMap) for pageName, markdown := range markdownMap { - f, err := os.Create(filepath.Join("..", "..", "docs", "reference", "types", fmt.Sprintf("%s.md", pageName))) + f, err := os.Create(filepath.Join("..", "..", "doc-site", "docs", "reference", "types", fmt.Sprintf("%s.md", pageName))) assert.NoError(t, err) _, err = f.Write(markdown) assert.NoError(t, err) diff --git a/internal/reference/reference.go b/internal/reference/reference.go index 2882180af..28fc1346d 100644 --- a/internal/reference/reference.go +++ b/internal/reference/reference.go @@ -660,7 +660,7 @@ func GenerateObjectsReferenceMarkdown(ctx context.Context) (map[string][]byte, e fftypes.JSONObject{}, } - return generateMarkdownPages(ctx, types, simpleTypes, filepath.Join("..", "..", "docs", "reference", "types")) + return generateMarkdownPages(ctx, types, simpleTypes, filepath.Join("..", "..", "doc-site", "docs", "reference", "types")) } func getType(v interface{}) reflect.Type { @@ -683,7 +683,7 @@ func generateMarkdownPages(ctx context.Context, types []interface{}, simpleTypes for i, o := range types { pageTitle := getType(types[i]).Name() // Page index starts at 1. Simple types will be the first page. Everything else comes after that. - pageHeader := generatePageHeader(pageTitle, i+2) + pageHeader := generatePageHeader(pageTitle) b := bytes.NewBuffer([]byte(pageHeader)) markdown, _, err := generateObjectReferenceMarkdown(ctx, true, o, reflect.TypeOf(o), rootPageNames, simpleTypesNames, []string{}, outputPath) if err != nil { @@ -701,10 +701,11 @@ func generateSimpleTypesMarkdown(ctx context.Context, simpleTypes []interface{}, simpleTypeNames[i] = strings.ToLower(getType(v).Name()) } - pageHeader := generatePageHeader("Simple Types", 1) + pageHeader := generatePageHeader("Simple Types") b := bytes.NewBuffer([]byte(pageHeader)) for _, simpleType := range simpleTypes { + b.WriteString(fmt.Sprintf("## %s\n\n", reflect.TypeOf(simpleType).Name())) markdown, _, _ := generateObjectReferenceMarkdown(ctx, true, nil, reflect.TypeOf(simpleType), []string{}, simpleTypeNames, []string{}, outputPath) b.Write(markdown) } @@ -729,7 +730,7 @@ func generateObjectReferenceMarkdown(ctx context.Context, descRequired bool, exa return nil, nil, i18n.NewError(ctx, coremsgs.MsgReferenceMarkdownMissing, filename) } } else { - typeReferenceDoc.Description = []byte(fmt.Sprintf("{%% include_relative _includes/%s_description.md %%}\n\n", strings.ToLower(t.Name()))) + typeReferenceDoc.Description = []byte(fmt.Sprintf("{%% include-markdown \"./_includes/%s_description.md\" %%}\n\n", strings.ToLower(t.Name()))) } // Include an example JSON representation if we have one available @@ -748,7 +749,6 @@ func generateObjectReferenceMarkdown(ctx context.Context, descRequired bool, exa // buff is the main buffer where we will write the markdown for this page buff := bytes.NewBuffer([]byte{}) - buff.WriteString(fmt.Sprintf("## %s\n\n", t.Name())) // If we only have one section, we will not write H3 headers sectionCount := 0 @@ -885,9 +885,9 @@ func writeStructFields(ctx context.Context, t reflect.Type, rootPageNames, simpl case isEnum: fireflyType = generateEnumList(field) case fieldInRootPages: - link = fmt.Sprintf("%s#%s", strings.ToLower(fieldType.Name()), strings.ToLower(fieldType.Name())) + link = fmt.Sprintf("%s.md#%s", strings.ToLower(fieldType.Name()), strings.ToLower(fieldType.Name())) case fieldInSimpleTypes: - link = fmt.Sprintf("simpletypes#%s", strings.ToLower(fieldType.Name())) + link = fmt.Sprintf("simpletypes.md#%s", strings.ToLower(fieldType.Name())) case isStruct: link = fmt.Sprintf("#%s", strings.ToLower(fieldType.Name())) } @@ -903,6 +903,7 @@ func writeStructFields(ctx context.Context, t reflect.Type, rootPageNames, simpl } } if isStruct && !tableAlreadyGenerated && !fieldInRootPages && !fieldInSimpleTypes { + subFieldBuff.WriteString(fmt.Sprintf("## %s\n\n", fieldType.Name())) subFieldMarkdown, newTableNames, _ := generateObjectReferenceMarkdown(ctx, false, nil, fieldType, rootPageNames, simpleTypeNames, generatedTableNames, outputPath) generatedTableNames = newTableNames subFieldBuff.Write(subFieldMarkdown) @@ -916,24 +917,9 @@ func writeStructFields(ctx context.Context, t reflect.Type, rootPageNames, simpl return tableRowCount } -func generatePageHeader(pageTitle string, navOrder int) string { +func generatePageHeader(pageTitle string) string { return fmt.Sprintf(`--- -layout: default title: %s -parent: Core Resources -grand_parent: pages.reference -nav_order: %v --- - -# %s -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- -`, pageTitle, navOrder, pageTitle) +`, pageTitle) } diff --git a/internal/reference/reference_test.go b/internal/reference/reference_test.go index 86dbd4594..0d4b70cf2 100644 --- a/internal/reference/reference_test.go +++ b/internal/reference/reference_test.go @@ -40,7 +40,7 @@ func TestCheckGeneratedMarkdownPages(t *testing.T) { assert.NotNil(t, markdownMap) for pageName, markdown := range markdownMap { - b, err := os.ReadFile(filepath.Join("..", "..", "docs", "reference", "types", fmt.Sprintf("%s.md", pageName))) + b, err := os.ReadFile(filepath.Join("..", "..", "doc-site", "docs", "reference", "types", fmt.Sprintf("%s.md", pageName))) assert.NoError(t, err) expectedPageHash := sha1.New() expectedPageHash.Write(b)