@gamechanger-finance/gc

v1.1.1

Published

a month ago

Official GameChanger Wallet library and CLI for integrating with Cardano dapps and solve other tasks (https://gamechanger.finance/)

GameChanger Wallet Library and CLI

Official GameChanger Wallet library and CLI for integrating Cardano via intents in links, QRs, dapps, web, screens, social media and solve other related tasks (https://gamechanger.finance/)

Complete refactor for Node v24.x.x . Supports all GameChanger Wallet V2.x.x flavors

Try it online:

✨ Kitchen Sink Dapp ✨

100 % backend-less: (no special backend required)
All the supported outputs formats for you to integrate or share
All the supported code generation languages for you to integrate

Example CLI/Library outputs:

To run web based examples:

$ npm run examples

To run the backend example:

$ npm run examples:express

html and react outputs are richer shared-state app boilerplates with local storage persistence that can host multiple actions (intent scripts coded in GCScript DSL) in one dapp and auto-render end-user UI from the intent code itself.

html-zero is the minimal zero-dependency flavor aimed at highly resilient, offline-ready, small-footprint frontends for long term reliability that can be stored on-chain with GCFS and work without any dependencies or centralized points of failure.

express is a minimal Node/Express backend example that redirects browser users to the wallet and then captures the response via "webhook" redirection.

Install CLI

$ npm install --global @gamechanger-finance/gc

Node target: >=24.12.0

Install Library

$ npm install -s @gamechanger-finance/gc

Import library on your projects:

For importing on html document:

Install:
  $ npm install -s @gamechanger-finance/gc
    or
  copy or host individual file 'dist/browser.min.js'

Load locally:
  <script src='dist/browser.min.js'></script>

Load using CDN :
  <script src="https://cdn.jsdelivr.net/npm/@gamechanger-finance/gc/dist/browser.min.js"></script>

Use:
  const {gc} = window;

For Node.js / React / Vite / webpack projects:

Install:
  $ npm install -s @gamechanger-finance/gc
Use (ESM default export):
  import gc from '@gamechanger-finance/gc'
Use (ESM named exports):
  import {gc, encode, snippet, encodings} from '@gamechanger-finance/gc'
Use (CommonJS):
  const gc = require('@gamechanger-finance/gc')

Local repository build targets:
  import gc from './dist/nodejs.js'
  const gc = require('./dist/nodejs.cjs')

Distribution targets

Published artifacts kept for npm and CDN usage:

dist/browser.js
dist/browser.min.js
dist/nodejs.cjs
dist/nodejs.js
dist/index.d.ts and the emitted declaration graph under dist/** for TypeScript consumers

Package entrypoints:

ESM / Node: import gc from "@gamechanger-finance/gc"
CommonJS / Node: const gc = require("@gamechanger-finance/gc")
Browser global: const {gc} = window

The Node and CLI QR path no longer depends on canvas / easyqrcodejs-nodejs at install time. Styled QR output is generated from EasyQRCodeJS SVG output and rasterized on Node only when PNG output is requested.

The browser bundle now keeps the Node-only QR runtime isolated from browser-targeted builds, so bundlers such as Vite can consume the package without pulling @napi-rs/canvas, jsdom, or the Node EasyQRCodeJS runtime into browser dependency graphs.

For local packaging smoke tests during development:

npm run pack:local

Library usage:

Encode dapp intent (dapp -> wallet message):

//GCScript: the DSL scripting language to interact with GameChanger Wallet
const gcscript = {
  type: 'script',
  title: '🚀 Connect with dapp?',
  description:
    'About to share your basic public wallet information to the dapp',
  exportAs: 'connect',
  run: {
    name: {
      type: 'getName'
    },
    address: {
      type: 'getCurrentAddress'
    },
    spendPubKey: {
      type: 'getSpendingPublicKey'
    },
    stakePubKey: {
      type: 'getStakingPublicKey'
    },
    addressInfo: {
      type: 'macro',
      run: "{getAddressInfo(get('cache.address'))}"
    }
  }
}

const url = await gc.encode.url({
  input: JSON.stringify(gcscript), // GCScript is pure JSON code, supported on all platforms
  apiVersion: '2', //APIV2
  network: 'mainnet', // mainnet or preprod
  encoding: 'gzip', //suggested, default message encoding/compression
  refAddress: 'addr1...', // optional - appends ref=<address>. For referral programs, a valid Cardano address under the same `network`
  disableNetworkRouter: false, // optional - by default appends networkTag=<network>. Set true to avoid prompting a network switch.
  urlPattern: 'http://localhost:3000/api/2/run/{gcscript}' // optional - override the default wallet URL pattern (must include {gcscript})
})

then redirect users to the URL like:

<a href="${url}">Connect with GC Wallet</a>

or render a QR encoded URL image like this:

const pngDataURI = gc.encode.qr({
  input: JSON.stringify(gcscript),
  apiVersion: '2',
  network: 'mainnet',
  encoding: 'gzip',
  refAddress: 'addr1...', // optional - appends ref=<address>. For referral programs, a valid Cardano address under the same `network`
  disableNetworkRouter: false, // optional - by default appends networkTag=<network>. Allows to stop requesting the user to switch to the network specified in `network` tag
  urlPattern: 'http://localhost:3000/api/2/run/{gcscript}', // optional - override the default wallet URL pattern (must include {gcscript})
  qrResultType: 'png'
})

then redirect users with the QR code like:

<image src="${pngDataURI}">Scan QR code to connect</image>

By default, gc.encode.url(...) and gc.encode.qr(...) handlers append networkTag=<network> to generated wallet URLs. Set disableNetworkRouter: true to skip that query string. When refAddress is provided, handlers also append ref=<address> while preserving any query string data already present in the base URL pattern.

Snippet customization (html / html-zero / react / button / express)

All snippet handlers support:

urlPattern (string): override the wallet URL pattern used by snippet-generated code and defaults (must be an absolute URL and contain {gcscript}).
snippetArgs (object): per-placeholder overrides for snippet templates. Values are injected as-is.

Special snippetArgs.defaultIntents can override the entire defaultIntents JS object literal (comments allowed). This override has priority over the single intent injected from the provided input script.

Decode intent execution results (wallet -> dapp message):

//Once GC Wallet executes an intent script, it can return arbirary JSON data to be exported back to the dapp
const resultObj = await gc.encodings.msg.decoder(resultRaw)
console.log(resultObj)

and will log something like:

{
  "exports": {
    "connect": {
      "name": "MyCardanoWallet",
      "address": "addr1q8aw6dzpw3cld828cqywp0sql4sxfw6syhzyh2kfcfccakddqwj2u3djrag0mene2cm9elu5mdqmcz9zc2rzgq7c5g6qshxn7l",
      "spendPubKey": {
        "pubKeyHex": "48362707efe478336740139127d8468aca10bf1358d2ab903d2d58876c99733b",
        "pubKeyHashHex": "faed34417471f69d47c008e0be00fd6064bb5025c44baac9c2718ed9",
        "derivationKind": "spend"
      },
      "stakePubKey": {
        "pubKeyHex": "9bef2297c79a52da05c33e99097e806e44ddda04e0dbaf7afef9274a64059557",
        "pubKeyHashHex": "cb6785612a53f5a093f38212db67bf4da23881d0fcf99518d02463a0",
        "derivationKind": "stake"
      },
      "addressInfo": {
        "isByron": false,
        "isReward": false,
        "isEnterprise": false,
        "isPointer": false,
        "isPaymentScript": false,
        "isStakingScript": false,
        "paymentScriptHash": "",
        "stakingScriptHash": "",
        "isScript": false,
        "kind": "base",
        "isCardano": true,
        "isShelley": true,
        "isBase": true,
        "isPaymentKey": true,
        "isStakingKey": true,
        "paymentKeyHash": "faed34417471f69d47c008e0be00fd6064bb5025c44baac9c2718ed9",
        "stakingKeyHash": "ad03a4ae45b21f50fde67956365cff94db41bc08a2c2862403d8a234",
        "rewardAddress": "stake1uxks8f9wgkep758aueu4vdjul72dksdupz3v9p3yq0v2ydqpd3mre",
        "network": "mainnet",
        "networkId": 1,
        "identity": {
          "scriptHex": "8201818200581cfaed34417471f69d47c008e0be00fd6064bb5025c44baac9c2718ed9",
          "scriptHash": "ddb4f2d0f44774964f57b444995e4a4a750d7b452a7177e739f8e21c",
          "scriptRefHex": "d818582582008201818200581cfaed34417471f69d47c008e0be00fd6064bb5025c44baac9c2718ed9"
        }
      }
    }
  }
}

Important:

"Connection intents" that share basic wallet information to dapps are the default sample script used in all examples here
Connection intents like these are not mandatory: Intent-based dapps may not require to pre-connect in order to work!
For simplicity sake these conection examples does not address:
- signature validation
- challenge validation
- HTTP origin validation
- nor encrypts comms beyond SSL against MITM attacks
A highly secure connection intent could be added in the future (let us know your needs!)

CLI Usage

✨ GameChanger Wallet CLI:
        Official GameChanger Wallet library and CLI for integrating it with Cardano dapps and solve other related tasks (https://gamechanger.finance/)

Usage
        $ gamechanger-cli [network] [action] [subaction]

Networks: 'mainnet' | 'preprod'

Actions:
        'encode':
                'url'     : generates a ready to use URL dApp connector from a valid GCScript
                'qr'      : generates a ready to use URL dApp connector encoded into a QR code image from a valid GCScript
        'snippet':
                'html'      : generates a ready to use HTML dApp with shared app state, multi-intent UX, and auto-rendered intent argument UI from a valid GCScript
                'html-zero' : generates a highly resilient offline-ready zero-dependency HTML dApp for mission-critical and on-chain hosted frontends from a valid GCScript
                'button'    : generates a ready to use HTML embeddable button snippet with a URL connector from a valid GCScript
                'express'   : generates a ready to use Node JS Express backend that redirects browser users to connect with the wallet, from a valid GCScript
                'react'     : generates a ready to use React dApp with shared app state, multi-intent UX, and auto-rendered intent argument UI from a valid GCScript
Options:
        --args [gcscript] | -a [gcscript]:  Load GCScript from arguments

        --file [filename] | -a [filename]:  Load GCScript from file
        without --args or --file         :  Load GCScript from stdin

        --outputFile [filename] -o [filename]:  The QR Code, HTML, html-zero, button, nodejs, or react output filename
        without --outputFile                 :  Sends the QR Code, HTML, html-zero, button, nodejs, or react output file to stdin

        --apiVersion [1 | 2] | -v [1 | 2]:  Target GameChanger Wallet v1 or v2

        --encoding [see encodings below] | -v [see encodings below]:  Target GameChanger Wallet v1 or v2 messaging encodings
        Valid encodings by apiVersion:
        {"2":["json-url-lzma","gzip","base64url"]}

        --template [see templates below] | -t [see templates below]: QR code predefined styles
        Valid templates: default, boxed or printable

        --serve | -S : Serve code snippet outputs on http://localhost:3000

        --refAddress [cardanoAddress] | -r [cardanoAddress]: Append ref=<address> to generated wallet URLs and QRs

        --disableNetworkRouter | -R : Do not append the default networkTag=<network> query string parameter

        --urlPattern [url] | -u [url] : Override the default wallet URL pattern (must include {gcscript})

        --snippetArgs [json] | -A [json] : JSON map of snippet template overrides (snippet actions only)

Examples

        ⭐ URL encoding:
                $ gamechanger-cli mainnet encode url -v 2 -f examples/connect.gcscript
                https://wallet.gamechanger.finance/api/2/run/1-H4sIAAA...?networkTag=mainnet

                $ gamechanger-cli mainnet encode url -v 2 -r addr1... -f examples/connect.gcscript
                https://wallet.gamechanger.finance/api/2/run/1-H4sIAAA...?networkTag=mainnet&ref=addr1...

                $ gamechanger-cli mainnet encode url -v 2 -a '{"title":"Get Address","description":"Do you authorize to share address to dapp?","type":"script","exportAs":"MyData","run":{"address":{"type":"getCurrentAddress"}}}'
                https://wallet.gamechanger.finance/api/2/run/1-H4sIAAA...?networkTag=mainnet

                $ cat examples/connect.gcscript | gamechanger-cli mainnet encode url -v 2
                https://wallet.gamechanger.finance/api/2/run/1-H4sIAAA...?networkTag=mainnet

        ⭐ QR encoding:
                $ gamechanger-cli preprod encode qr -v 2 -a '{"title":"Get Address","description":"Do you authorize to share address to dapp?","type":"script","exportAs":"MyData","run":{"address":{"type":"getCurrentAddress"}}}' > qr_output.png

                $ gamechanger-cli mainnet encode qr -v 2 -o examples/qr_output.png -a '{"title":"Get Address","description":"Do you authorize to share address to dapp?","type":"script","exportAs":"MyData","run":{"address":{"type":"getCurrentAddress"}}}'

                $ cat examples/connect.gcscript | gamechanger-cli mainnet encode qr -v 2 -o examples/qr_output.png


                $ gamechanger-cli mainnet encode qr -e gzip  -v 2 -f examples/connect.gcscript -o examples/qr_output.png


        Code generation and serve dapp (-S):

        ⭐ HTML code:
                $ gamechanger-cli preprod snippet html -v 2 -S -o examples/htmlDapp.html -f examples/connect.gcscript
                🚀 Serving output with the hosted Gamechanger library on http://localhost:3000

        ⭐ HTML Zero code:
                $ gamechanger-cli mainnet snippet html-zero -v 2 -S -o examples/htmlZeroDapp.html -f examples/connect.gcscript
                🚀 Serving output with the hosted Gamechanger library on http://localhost:3000

        ⭐ ReactJS code:
                $ gamechanger-cli mainnet snippet react -v 2 -S -o examples/reactDapp.html -f examples/connect.gcscript
                🚀 Serving output with the hosted Gamechanger library on http://localhost:3000

        ⭐ HTML Button snippet:
                $ gamechanger-cli mainnet snippet button -v 2 -S -o examples/connectButton.html -f examples/connect.gcscript
                🚀 Serving output with the hosted Gamechanger library on http://localhost:3000

        ⭐ Express backend code:
                $ gamechanger-cli mainnet snippet express -v 2 -o examples/expressBackend.js -f examples/connect.gcscript
                $ node examples/expressBackend.js
                🚀 Express NodeJs Backend serving output URL with the hosted Gamechanger library on http://localhost:3000/

Breaking Changes Notice

Generated code outputs are now much richer and complex than the ones produced over the last years. For improvements and maintainance these may require more internal breaking changes in their internal design, decoupling from the versioning strategy of the actual library. If you need special treatment on outputs let us know or consider forking for your use case.

Resources

License

MIT

Development

npm install
npm run build
npm test