How to register an effect

Date	Responsible	Changes
November 29, 2022	@Tomislav Herman	Initial version
January 20, 2023	@Tomislav Herman	Updated code example to match latest signing api from ledger-sdk.
February 10, 2023	@Omar Monterrey	SDK Options refactoring (`url` to `server` and `key` to `signer`)
February 17, 2023	@Tomislav Herman	Updated webhook urls to bridge interface convention: `v2/effects/:handle`
February 27, 2023	@Omar Monterrey	Refactored `signer.schema` → `signer.format`
March 9, 2023	@Tomislav Herman	Refactored `ledger` → `sdk`
November 16, 2023	@Luis Fidelis	Add `bridge` action schema

Effects are used to extend the ledger core functionalities by observing and reacting on events raised when a change occurs with ledger data.

We will register an effect which is triggered by an event with signal balance-received, but only when wallet with handle bank1 receives a balance in usd symbol. When triggered, the effect will execute webhook action which sends a HTTP POST request with event payload to the endpoint defined in webhook action, or to the server defined in a bridge if the effect action schema if bridge. We will assume that there is a local HTTP server which listens on http://localhost:3000/v2/effects/bank1-balance-received endpoint.

Registering a webhook effect

Example in Node.js by using @minka/ledger-sdk:

import { LedgerSdk } from '@minka/ledger-sdk'
 
const sdk = new LedgerSdk({
  server: '<ledger URL>',
  signer: {
		format: 'ed25519-raw',
		public: '<ledger public key>'
	}
})
 
const { effect } = await sdk.effect
  .init()
  .data({
    handle: 'bank1-balance-received',
		signal: 'balance-received',
    filter: {
			'wallet.data.handle': 'bank1',
			'symbol.data.handle': 'usd'
		},
		action: {
			schema: 'webhook',
			endpoint: 'http://localhost:3000/v2/effects/bank1-balance-received'
		},
		access: []
  })
  .hash()
  .sign([{ keyPair: yourKeyPair }])
  .send()

Or by using @minka/cli:

$ minka effect create
? Handle: bank1-balance-received
? Signal: balance-received
? Add filter? Yes
? Field name: wallet.data.handle
? Field value: bank1
? Add another field? Yes
? Field name: symbol.data.handle
? Field value: usd
? Add another field? No
? Action schema: webhook
? Webhook endpoint? http://localhost:3000/v2/effects/bank1-balance-received
? Add custom data?: No
? Signer: your-key
 
✅ Effect created successfully:
Handle: bank1-balance-received
Signal: balance-received
Filter:
 - wallet.data.handle: bank1
 - symbol.data.handle: usd
Action:
 - schema: webhook
 - endpoint: http://localhost:3000/v2/effects/bank1-balance-received
Signer: MCowBQYDK2VwAyEAqySfsabYtxyEwAYtJQRv0NyRkfjC65hmZ9ZwnCmsso4= (your-key)

Registering a bridge effect

Firstly, we need to setup a bridge in the ledger to receive an event when a balance is changed - received - in the system.

Via @minka/ledger-sdk :

import { LedgerSdk } from '@minka/ledger-sdk'
 
const sdk = new LedgerSdk({
  server: '<ledger URL>',
  signer: {
		format: 'ed25519-raw',
		public: '<ledger public key>'
	}
})
 
const { bridge } = await sdk.bridge
  .init()
  .data({
    handle: 'test-bridge',
    config: {
	    server: 'http://localhost:3000/v2',
    },
	  secure: [],
    access: [...],
    traits: ['events']
  })
  .hash()
  .sign([{ keyPair: yourKeyPair }])
  .send()

Or via @minka/cli :

$ minka bridge create
? Handle: test-bridge
? Server: http://localhost:3000/v2
? Define bridge traits? Yes
? Traits: events
? Add custom data? No
? Signer: your-key
 
✅ Bridge created successfully:
Luid: $brg.XLjS-hTaCpl_t07oP
Handle: test-bridge
Server: http://localhost:3100/v2
Signer: MCowBQYDK2VwAyEAqySfsabYtxyEwAYtJQRv0NyRkfjC65hmZ9ZwnCmsso4= (your-key)

The bridge should implement at least events trait to be able to receive effect calls.

Now we have our bridge, we can proceed and register the effect targeting the bridge created previously.

By using @minka/ledger-sdk:

import { LedgerSdk } from '@minka/ledger-sdk'
 
const sdk = new LedgerSdk({
  server: '<ledger URL>',
  signer: {
		format: 'ed25519-raw',
		public: '<ledger public key>'
	}
})
 
const { effect } = await sdk.effect
  .init()
  .data({
    handle: 'bank2-balance-received',
		signal: 'balance-received',
    filter: {
			'wallet.data.handle': 'bank1',
			'symbol.data.handle': 'usd'
		},
		action: {
			schema: 'bridge',
			bridge: 'test-bridge'
		},
		access: [...]
  })
  .hash()
  .sign([{ keyPair: yourKeyPair }])
  .send()

Or by using @minka/cli:

$ minka effect create
? Handle: bank2-balance-received
? Signal: balance-received
? Add filter? Yes
? Field name: wallet.data.handle
? Field value: bank1
? Add another field? Yes
? Field name: symbol.data.handle
? Field value: usd
? Add another field? No
? Action schema: bridge
? Bridge handle: test-bridge
? Add custom data?: No
? Signer: your-key
 
✅ Effect created successfully:
Handle: bank1-balance-received
Signal: balance-received
Filter:
 - wallet.data.handle: bank1
 - symbol.data.handle: usd
Action:
 - schema: bridge
 - bridge: test-bridge
Signer: MCowBQYDK2VwAyEAqySfsabYtxyEwAYtJQRv0NyRkfjC65hmZ9ZwnCmsso4= (your-key)

After that, the bridge will start to receive those events at

POST http://localhost:3000/v2/effects/bank2-balance-received .

Notice that bank2-balance-received is the handle of the effect created, so the endpoint

on the other side should be registered with same value.

How to handle effect webhook calls

About Bridges

How to register an effect

Registering a webhook effect

Registering a bridge effect

Related

On this page