1. Usando o Oracle Blockchain Platform
  2. Crie Chaincodes com o Low-Code Blockchain App Builder
  3. Usando a Extensão do Blockchain App Builder para o Visual Studio Code
  4. Crie um Projeto de Chaincode com a Extensão de Código VS do Blockchain App Builder
  5. Arquivo de Especificação de Entrada

Arquivo de Especificação de Entrada

O comando de inicialização do Blockchain App Builder lê o arquivo de especificação de entrada e gera o projeto com várias ferramentas para ajudar no processo de desenvolvimento de chaincode.

Com o arquivo de especificação, você pode especificar várias definições e comportamentos de ativos, declaração de método CRUD e não CRUD, métodos personalizados, validação de argumentos, marshalling/desestruturação automática, capacidade de persistência transparente e chamada de consultas de dados avançados usando SQL SELECTs ou CouchDB Query Language. Esses recursos serão gerados para você.

Para obter informações sobre como especificar ativos de token, consulte estes tópicos:
O arquivo de especificação pode ser gravado em yaml ou json. Você pode ver arquivos de especificação de amostra em ambos os formatos no download do pacote Blockchain App Builder:
  • Fabcar-Typescript.yml
  • Marbles-Go.yml

Observação:

De acordo com as convenções Go, os nomes exportados começam com uma letra maiúscula. Portanto, todas as propriedades e métodos do ativo devem ter nomes começando com letras maiúsculas no arquivo de especificação.

Estrutura do Arquivo de Especificação

Normalmente, você estrutura um arquivo de especificação da seguinte maneira:

assets: 
    name:
    type:
    properties:
        name:
        type:
        id:
        derived:
           strategy:
           algorithm:
           format:
        mandatory:
        default:
        validate:
    methods:
        crud:
        others:
customMethods:

O Blockchain App Builder suporta dois tipos de ativos especiais, ativos incorporados e ativos de token, além de ativos genéricos sem tipo especificado. Os ativos especiais são definidos como type: embedded ou type: token na seção assets: do arquivo de especificação.

Tabela 7-2 Descrições e Exemplos de Parâmetro de Arquivo de Especificação

Entrada Descrição Exemplos
assets:

Essa propriedade assume a definição e o comportamento do ativo. Você pode fornecer várias definições de ativos aqui.

  
name:

O nome do ativo.

Estes nomes são reservados. Não use esses nomes para ativos.
  • account
  • role
  • hold
  • token
  • authorization
  • tokenAdmin
  • Account
  • Role
  • Hold
  • Token
  • Authorization
  • TokenAdmin
 
name: owner # Information about the owner
type:

Tipos de ativos

Os seguintes tipos de ativos especiais são suportados:
  • embedded
  • token

Se você não especificar um parâmetro type na seção assets, o ativo será do tipo genérico.

 
type:

tipo: incorporado

Se essa propriedade for definida como embedded, o ativo será definido como um ativo incorporado. Os ativos incorporados não têm métodos CRUD e precisam fazer parte de outro ativo para serem armazenados no razão.

No exemplo, a propriedade address é incorporada e definida em outro ativo.

Os ativos incorporados não suportam referências circulares. Por exemplo, no exemplo anterior, o ativo address não pode conter uma referência ao ativo employee.

Ativo: employee
name: employee
  properties:
     name: employeeId
     type: string
     mandatory: true
     id: true

     name: firstName
     type: string
     validate: max(30)
     mandatory: true

     name: lastName
     type: string
     validate: max(30)
     mandatory: true

     name: age
     type: number
     validate: positive(),min(18)

     name: address
     type: address
Ativo: address
name: address

type: embedded

properties:
   name: street
   type: string

   name: city
   type: string

   name: state
   type: string

   name: country
   type: string
properties:

Descreva todas as propriedades de um ativo.

  
name:

O nome da propriedade.

 
name: ownerId # Unique ID for each owner
id:
  • verdadeiro

Especifica o identificador deste ativo. Esta propriedade é obrigatória.

 
name: owner            # Information about the owner
properties:
     name: ownerId    # Unique ID for each owner
     type: string
     mandatory: true
     id: true
     name: name        # Name of the owner
     type: string
     mandatory: true
type:

Tipos de propriedades

Os seguintes tipos de propriedades básicas são suportados:
  • number
  • float
  • string
  • boolean
  • date
  • array
Para chaincodes Go, number é mapeado para int e float é mapeado para float64. Outros tipos não são suportados atualmente, incluindo os seguintes tipos:
  • complex
  • unsigned/signed int
  • 8/16/32/64 bits
 
name: year        # Model year
                    type: number
                    mandatory: true
                    validate: min(1910),max(2020)
                    name: color       # Color - no validation as color names are innumerable
                    type: string
                    mandatory: true
derived:

Esta propriedade especifica que a propriedade id é derivada de outras chaves. As propriedades dependentes devem ser tipo de dados string e não um ativo incorporado.

Esta propriedade tem dois parâmetros obrigatórios:
  • strategy: obtém valores de concat ou hash.
  • format: usa um array de strings de especificação e valores a serem usados pela estratégia.
Exemplo 1
  • A propriedade employeeID depende das propriedades firstName e lastName.
  • Essa propriedade é uma concatenação dos valores listados no array format.
  • IND%1#%2%tIND é o 0o índice no array e descreve o formato final.
  • %n é um especificador de posição que extrai seus valores dos outros índices no array.
  • %t indica que o valor deve ser stub.timestamp no cabeçalho do canal.
  • Se você precisar usar o caractere % na string format, ele deverá ter escape com outro %.
  • O formato final neste exemplo seria: INDfirstName#lastName1606885454916IND
Exemplo 2:
  • Ao usar hash, você também deve usar o parâmetro algorithm. O padrão é sha256; md5 também é suportado.
  • IND%1#%2%t é o 0o índice no array e descreve o formato final.
  • %n é um especificador de posição que extrai seus valores dos outros índices no array.
  • %t indica que o valor deve ser stub.timestamp no cabeçalho do canal.
  • Se você precisar usar o caractere % na string format, ele deverá ter escape com outro %.
Exemplo 1
name: employee
  properties:
     name: employeeId
     type: string
     mandatory: true
     id: true
     derived:
         strategy: concat
         format: ["IND%1#%2%tIND","firstName","lastName"]

     name: firstName
     type: string
     validate: max(30)
     mandatory: true

     name: lastName
     type: string
     validate: max(30)
     mandatory: true

     name: age
     type: number
     validate: positive(),min(18)
Exemplo 2
name: account
  properties:
     name: accountId
     type: string
     mandatory: true
     id: true
     derived:
         strategy: hash
         algorithm: 'sha256'
         format: ["IND%1#%2%t","bankName","ifsccode"]

     name: bankName
     type: string
     validate: max(30)
     mandatory: true

     name: ifsccode
     type: string
     mandatory: true
mandatory:
  • verdadeiro
  • falso

A propriedade correspondente é obrigatória e não pode ser ignorada durante a criação de um ativo.

 
name: phone       # Phone number - validate as (ddd)-ddd-dddd where dashes could also be periods or spaces
type: string
mandatory: true
validate: /^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/
name: cars        # The list of car VINs owned by this owner
type: string[]
mandatory: false
default:

Isso fornece o valor padrão dessa propriedade.

  
validate:

A propriedade fornecida é validada em relação a algumas das validações prontas para uso fornecidas pelo Blockchain App Builder. Você pode encadear validações se tiver certeza de que a cadeia é válida.

Se a propriedade validate não for fornecida, a validação será feita somente na propriedade type.

 
validate:

tipo: número
  • positivo()
  • negativo()
  • mínimo()
  • máximo()

Essas validações podem ser encadeadas separadas por vírgulas. 

name: offerApplied
type: number
validate: negative(),min(-4)
name: year  # Model year
type: number
mandatory: true
validate: min(1910),max(2020)
validate:

tipo: string
  • min()
  • max()
  • email()
  • url()
  • /regex/ - suporta PHP regex

Para códigos de cadeia Go, as expressões regulares que contêm determinados caracteres reservados ou caracteres de espaço em branco devem ter escape adequado.

 
name: website 
type: string
mandatory: false
validate: url()
name: phone  # Phone number - validate as (ddd)-ddd-dddd where dashes could also be periods or spaces
type: string
mandatory: true
validate: /^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/
name: Color #Color can be red, blue, or green
type: string
mandatory: true
validate: /^\\s*(red|blue|green)\\s*$/
validate:

tipo: boolean
  • verdadeiro
  • falso

No exemplo, a validação da propriedade active é pelo próprio tipo (boolean) 

name: active
type: boolean
validate:

tipo: array

Por tipo em si, na forma de type: number[], isso transmite que o array é do tipo número.

Você pode informar limites para o array no formato number[1:5], o que significa que o tamanho mínimo é 1, o máximo é 5. Se um deles for evitado, apenas min/max será considerado. 

name: items
type: number[:5]
validate:

tipo: data
  • min()
  • max()
A data deve ser um destes formatos:
  • YYYY-MM-DD
  • YYYY-MM-DDTHH:MM:SSZ, em que T separa a data da hora, e Z indica UTC. As compensações de fuso horário podem substituir o Z como em -05:00 para Horário de Verão Central. 
name: expiryDate
type: date
validate: max('2020-06-26')
name: completionDate
type: date
validate: min('2020-06-26T02:30:55Z')
methods:

Use esta opção para indicar qual CRUD (Criar/Ler/Atualizar/Excluir) ou métodos adicionais devem ser gerados.

Por padrão, se nada for inserido, todos os métodos CRUD e outros serão gerados.

 
methods:
    crud: [create, getById, update, delete]
    others: [getHistoryById, getByRange]
crud:
  • create
  • getByID (leitura)
  • update
  • delete

Se essa matriz for deixada vazia, nenhum método CRUD será criado.

Se o parâmetro crud não for usado, todos os quatro métodos serão criados por padrão.

O parâmetro crud não se aplica aos ativos token e embedded. 

methods:
    crud: [create, getById, delete]
    others: [] # no other methods will be created
others:
  • getHistoryById
  • getByRange

getHistoryById retorna o histórico do ativo em uma lista.

getByRange retorna todos os ativos em um determinado intervalo. Para obter mais informações, consulte "getByRange" (TypeScript) e "GetByRange" (Go).

Se essa matriz for deixada vazia, nenhum outro método será criado.

Se o parâmetro others não for usado, os dois métodos serão criados por padrão.

O parâmetro others não se aplica aos ativos token e embedded. 

methods:
    crud: [create, delete]
    others: [] # no other methods will be created
      methods:
        crud: [create, getById, update, delete]
        others: [getHistoryById, getByRange]
customMethods:

Essa propriedade cria modelos de método personalizados invocáveis no arquivo do controlador principal. Ele pega a assinatura do método e cria a declaração de função no arquivo do controlador.

Você pode fornecer declarações de função específicas do idioma aqui.

Fornecemos um método personalizado chamado executeQuery. Se ele for adicionado ao arquivo de especificação, ele detalhará como o Berkeley DB SQL e as consultas avançadas CouchDB podem ser executadas. Esse método só pode ser chamado quando você está conectado ao Oracle Blockchain Platform Cloud ou à Enterprise Edition.

TypeScript

customMethods:
    - executeQuery
    - "buyCar(vin: string, buyerId: string, sellerId: string, price: number, date: Date)"
    - "addCar(vin: string, dealerId: string, price: number, date: Date)"

Go

customMethods:
    - executeQuery
    - "BuyCar(vin string, buyerId string, sellerId string, price int)"
    - "AddCar(vin string, dealerId string, price int)"